hoi4-agent-tools 3.0.9 → 3.1.0

package/CHANGELOG.md

@@ -2,7 +2,29 @@
 
 ## Unreleased
 
-No unreleased changes.
+## 3.1.0 - 2026-09-20
+
+- Reuse authenticated content-addressed parsed documents and file-local index segments across authorized local processes while revalidating current source bytes, load order, shadowing, workspace topology, and principal scope.
+- Rebuild exact indexes from immutable segments, retain typed reverse source dependencies, and heal malformed or tampered persistent cache entries without trusting timestamps or file sizes.
+- Run event, technology, probability, map, GUI, and focus analysis in fixed-entry isolated workers backed by durable authenticated jobs, revision-fenced ownership, bounded retention, and source-revision result checkpoints.
+- Advertise optional negotiated MCP tasks for all long-running domain calls while preserving exact ordinary-call results, progress, cancellation, linked resources, tool errors, and both stdio and HTTP compatibility.
+- Share task execution, authorization, and all 23 domain tool definitions with an MCP 2026-07-28 Tasks extension adapter, routed by production stdio and authenticated HTTP entry points.
+- Share `hoi4.job_inspect` and `hoi4.job_cancel` between protocol adapters as responsive, principal-private compatibility controls that remain available while domain execution slots are occupied.
+- Share the bounded probability-analysis prompt metadata and body between protocol adapters without starting jobs or source analysis.
+- Advertise the same server instructions through legacy initialization and modern discovery.
+- Deliver opt-in modern request progress through the SDK's related-notification API, preserving ordered heartbeats and cancellation over connection and auto-streaming production HTTP serving.
+- Pin each bounded stdio connection to its opening protocol era and route authenticated modern HTTP claims through strict SDK validation without changing legacy stateful sessions or the existing request-security gates.
+- Share the two opt-in ChaosX private-tool implementations between stdio protocol generations while keeping them absent from ordinary and HTTP catalogs.
+- Pin patched Sharp, Hono, Vitest, and coverage packages while retaining the exact dependency graph in the lockfile.
+- Require caller-stable request keys for native background focus, GUI, and map rewrites; deduplicate exact retries independently of polling hints and reject conflicting reuse.
+- Derive new job IDs from private server state, preserve authenticated earlier retry receipts without replay, and authenticate modern task handles before execution admission or cancellation.
+- Renew only task-visibility metadata for exact retries of expired rewrite receipts, preserving terminal outcomes and source edits through native and ordinary calls in both protocol generations.
+- Share bounded artifact-resource reads between protocol generations, including exact byte ranges, continuation links, manifest projection, and workspace-grant checks.
+- Bind rewrite transactions and domain completion recipes before source application, reconcile stopped workers without replanning, and retain post-write validation artifacts without changing immutable plan hashes.
+- Retain revision-addressed event and technology graphs for comparisons after process restart, and preserve explicit helper, source, candidate, node, edge, and render coverage boundaries.
+- Add opt-in bounded `helper_expansion` pages for event and technology inspection, preserving distinct source call paths and resumable principal- and revision-bound cursors without retaining completed traversal history.
+- Mark depth- and projection-truncated materialized helper graphs incomplete, and retain explicit cycle, dynamic-reference, source-coverage, and page-retention boundaries.
+- Harden Windows atomic job publication, bounded pre-dispatch worker-lease transfer retries, disconnect recovery, principal isolation, task expiry, and mutation-receipt retention under concurrent clients.
 
 ## 3.0.9 - 2026-09-08
 

package/README.md

@@ -71,6 +71,8 @@ On non-Windows systems, use `hoi4-agent-tools` as the command. Agentic HOI4 repo
 | `hoi4.event_inspect`        | Scan, trace, explain, lint, or assess event chains and their state flow.                  |
 | `hoi4.event_render`         | Render source-linked event routes, options, timing, state, scope, and unresolved edges.   |
 | `hoi4.event_compare`        | Compare event-chain topology and diagnostics between revisions.                           |
+| `hoi4.job_inspect`          | Inspect durable background work or retrieve its completed tool result.                    |
+| `hoi4.job_cancel`           | Durably request cancellation of authorized background work.                               |
 | `hoi4.tech_inspect`         | Scan, trace, explain, lint, and assess technology and doctrine systems.                   |
 | `hoi4.tech_render`          | Render source layouts with real item sizes and year guides, plus dependencies and assets. |
 | `hoi4.tech_compare`         | Compare technology graphs, placements, references, diagnostics, and source overlays.      |
@@ -86,6 +88,8 @@ Set `HOI4_AGENT_TOOLS_CHAOSX=1` on the server process to expose the optional `ch
 
 Large outputs are linked `hoi4-agent://` resources. For resources over 1 MiB, follow the `continuationUri` returned in `_meta` until it is `null`; clients may also request byte ranges with `?offset=<bytes>&length=<bytes>`.
 
+Long-running domain calls advertise optional MCP task support. A task survives client disconnects and can be retrieved after reconnect; clients without task support keep the ordinary synchronous result contract. Native background rewrites require a stable caller-supplied `requestKey` so retries resolve to one durable mutation receipt. See [Persistent jobs and MCP tasks](docs/jobs.md).
+
 ## Coexistence with agent workflows
 
 HOI4 Agent Tools provides HOI4 domain operations without replacing repository instructions such as `AGENTS.md`, skills, plans, or subagents. Its optional weighted-logic prompt helps an agent scope one probability analysis and then returns control to the normal workflow.

package/dist/bin/stdio.js

@@ -1,18 +1,14 @@
 #!/usr/bin/env node
 import { canonicalJson } from '../hoi4_agent_tools/core/canonical.js';
-import { createMcpServer } from '../hoi4_agent_tools/mcp/server/create.js';
-import { BoundedStdioServerTransport, StdioFrameLimitError, StdioInvalidMessageError, StdioInvalidUtf8Error, } from '../hoi4_agent_tools/mcp/transports/bounded-stdio.js';
-import { FinalProtocolTransport } from '../hoi4_agent_tools/mcp/transports/protocol-gate.js';
+import { StdioFrameLimitError, StdioInvalidMessageError, StdioInvalidUtf8Error, } from '../hoi4_agent_tools/mcp/transports/bounded-stdio.js';
+import { serveNegotiatedStdio } from '../hoi4_agent_tools/mcp/transports/negotiated-stdio.js';
 import { createEngine } from '../hoi4_agent_tools/runtime.js';
 async function main() {
     const engine = await createEngine();
-    const context = {};
-    const server = createMcpServer(engine, context);
-    if (process.env.HOI4_AGENT_TOOLS_CHAOSX === '1') {
-        const { registerChaosxTools } = await import('../hoi4_agent_tools/mcp/tools/chaosx.js');
-        registerChaosxTools(server, engine, context);
-    }
-    server.server.onerror = (error) => {
+    const chaosxTools = process.env.HOI4_AGENT_TOOLS_CHAOSX === '1'
+        ? await import('../hoi4_agent_tools/mcp/tools/chaosx.js')
+        : undefined;
+    const onerror = (error) => {
         const fatalInputError = error instanceof StdioFrameLimitError || error instanceof StdioInvalidUtf8Error;
         const rejectedMessage = error instanceof StdioInvalidMessageError;
         if (fatalInputError)
@@ -24,8 +20,23 @@ async function main() {
             message: error.message,
         })}\n`);
     };
-    const transport = new BoundedStdioServerTransport();
-    await server.connect(new FinalProtocolTransport(transport));
+    await serveNegotiatedStdio(engine, {
+        onerror,
+        onFailure: (error) => {
+            process.exitCode = 1;
+            process.stderr.write(`${canonicalJson({
+                level: 'error',
+                event: 'transport_startup_failed',
+                message: error instanceof Error ? error.message : String(error),
+            })}\n`);
+        },
+        ...(chaosxTools === undefined
+            ? {}
+            : {
+                createModernPrivateTools: chaosxTools.createChaosxToolOperations,
+                registerLegacy: (server) => chaosxTools.registerChaosxTools(server, engine, {}),
+            }),
+    });
 }
 main().catch((error) => {
     process.stderr.write(`${canonicalJson({

package/dist/hoi4_agent_tools/core/analysis-checkpoints.js

@@ -0,0 +1,82 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { z } from 'zod/v4';
+import { canonicalJson, hashCanonical } from './canonical.js';
+import { ServiceError } from './result.js';
+import { PACKAGE_VERSION } from '../version.js';
+const digest = z.string().regex(/^[a-f0-9]{64}$/u);
+const envelopeSchema = z
+    .object({
+    version: z.literal(1),
+    key: digest,
+    sourceRevision: digest,
+    state: z.json(),
+})
+    .strict();
+const active = new AsyncLocalStorage();
+/** Internal typed execution context; no transport or caller-supplied executable hooks. */
+export function withAnalysisCheckpoints(checkpoints, run) {
+    return active.run(checkpoints, run);
+}
+export function currentAnalysisCheckpoints() {
+    return active.getStore();
+}
+/** The authenticated job record commits to the exact immutable checkpoint bytes. */
+export function jobAnalysisCheckpoints(context) {
+    let checkpoint = context.checkpoint;
+    const workspace = context.engine.resolver.get(context.workspaceId, context.principal);
+    return {
+        async load(key, sourceRevision, schema) {
+            if (checkpoint?.cursor !== `analysis:${key}` || checkpoint.sourceRevision !== sourceRevision)
+                return undefined;
+            if (checkpoint.resourceUri === undefined || checkpoint.stateHash === undefined)
+                throw new ServiceError('ANALYSIS_CHECKPOINT_INVALID', 'Analysis checkpoint has no authenticated state');
+            const resource = await context.engine.artifacts.readLogical(workspace, checkpoint.resourceUri, {
+                mimeType: 'application/json',
+                maxBytes: 268_435_456,
+                maxChunks: 256,
+            }, context.signal);
+            const envelope = envelopeSchema.parse(JSON.parse(resource.bytes.toString('utf8')));
+            if (envelope.key !== key ||
+                envelope.sourceRevision !== sourceRevision ||
+                hashCanonical(envelope) !== checkpoint.stateHash)
+                throw new ServiceError('ANALYSIS_CHECKPOINT_INVALID', 'Analysis checkpoint identity or content does not match its job');
+            return schema.parse(envelope.state);
+        },
+        async save(key, sourceRevision, state, completed, total) {
+            context.signal.throwIfAborted();
+            const envelope = envelopeSchema.parse({ version: 1, key, sourceRevision, state });
+            await context.engine.artifacts.withAtomicChunkedWrites(workspace, [
+                {
+                    name: 'analysis-checkpoint.json',
+                    mimeType: 'application/json',
+                    content: canonicalJson(envelope),
+                    provenance: {
+                        kind: 'analysis-checkpoint',
+                        toolVersion: PACKAGE_VERSION,
+                        schemaVersion: '1',
+                        sourceHashes: {},
+                        metadata: { key, sourceRevision },
+                    },
+                    description: 'Revision-bound internal dependency-expansion checkpoint',
+                },
+            ], async ([resource], physical) => {
+                const next = {
+                    sourceRevision,
+                    resourceUri: resource.uri,
+                    cursor: `analysis:${key}`,
+                    stateHash: hashCanonical(envelope),
+                    resources: physical.map(({ uri }) => uri),
+                };
+                // Publish the authenticated pin before releasing artifact admission. A competing
+                // writer therefore sees either the old complete checkpoint or the new one.
+                await context.saveCheckpoint(next);
+                checkpoint = next;
+            }, context.signal);
+            await context.progress({
+                completed,
+                total,
+                message: 'Expanding source-bound helper dependencies',
+            });
+        },
+    };
+}

package/dist/hoi4_agent_tools/core/artifact-resource.js

@@ -0,0 +1,173 @@
+import { canonicalJson } from './canonical.js';
+import { ServiceError } from './result.js';
+const artifactResourceLimit = 1_048_576;
+const artifactChunkMetadataKey = 'io.github.klimpaskov/hoi4-agent-tools.artifact-byte-range';
+const fatalUtf8Decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+export const artifactResourceDefinition = {
+    name: 'artifact',
+    uriTemplate: 'hoi4-agent://workspace/{workspaceId}/artifact/{sha256}/{provenanceHash}/{name}',
+    title: 'HOI4 review artifact',
+    description: 'Complete plans, diagnostics, layouts, previews, event graphs, routes, state and scope reports, comparisons, and diffs. Reads accept zero-based byte offset and positive byte length query selectors; each response reports its exact byte range and continuation URI in _meta.',
+    _meta: {
+        [artifactChunkMetadataKey]: {
+            version: 1,
+            unit: 'byte',
+            maxChunkSize: artifactResourceLimit,
+            selectors: {
+                offset: { type: 'integer', minimum: 0, default: 0 },
+                length: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: artifactResourceLimit,
+                    default: artifactResourceLimit,
+                },
+                metadata: { type: 'string', enum: ['manifest'], optional: true },
+            },
+        },
+    },
+};
+function assertResourceSelectors(uri, allowed) {
+    if (uri.hash !== '' || uri.username !== '' || uri.password !== '' || uri.port !== '') {
+        throw new ServiceError('RESOURCE_URI_INVALID', 'Resource URI is not canonical');
+    }
+    const allowedNames = new Set(allowed);
+    const seen = new Set();
+    for (const name of uri.searchParams.keys()) {
+        if (!allowedNames.has(name)) {
+            throw new ServiceError('RESOURCE_SELECTOR_INVALID', 'Resource selector is not supported');
+        }
+        if (seen.has(name)) {
+            throw new ServiceError('RESOURCE_SELECTOR_INVALID', 'Resource selectors may not be repeated');
+        }
+        seen.add(name);
+    }
+}
+function contentArtifactUri(uri) {
+    const contentUri = new URL(uri);
+    contentUri.search = '';
+    contentUri.hash = '';
+    return contentUri.href;
+}
+function exactUtf8Text(bytes) {
+    try {
+        const text = fatalUtf8Decoder.decode(bytes);
+        return Buffer.from(text, 'utf8').equals(bytes) ? text : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function artifactRangeParameter(uri, name, fallback, minimum, maximum = Number.MAX_SAFE_INTEGER) {
+    const raw = uri.searchParams.get(name);
+    if (raw === null)
+        return fallback;
+    if (!/^\d+$/u.test(raw)) {
+        throw new ServiceError('ARTIFACT_RANGE_INVALID', 'Artifact byte range is invalid');
+    }
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+        throw new ServiceError('ARTIFACT_RANGE_INVALID', 'Artifact byte range is invalid');
+    }
+    return value;
+}
+function artifactChunkMetadata(uri, metadata, totalSize, offset, returnedLength, requestedLength) {
+    const endExclusive = offset + returnedLength;
+    let continuationUri = null;
+    if (endExclusive < totalSize) {
+        const continuation = new URL(contentArtifactUri(uri));
+        continuation.searchParams.set('offset', String(endExclusive));
+        continuation.searchParams.set('length', String(requestedLength));
+        if (metadata !== null)
+            continuation.searchParams.set('metadata', metadata);
+        continuationUri = continuation.href;
+    }
+    return {
+        [artifactChunkMetadataKey]: {
+            version: 1,
+            unit: 'byte',
+            totalSize,
+            returnedRange: { offset, length: returnedLength, endExclusive },
+            complete: offset === 0 && returnedLength === totalSize,
+            continuationUri,
+        },
+    };
+}
+/** Shared bounded resource reader. URI ownership never supplies a principal or root grant. */
+export async function readArtifactResource(engine, uriInput, context, signal) {
+    signal.throwIfAborted();
+    let uri;
+    let workspaceId;
+    try {
+        if (uriInput.length > 8192)
+            throw new Error('URI exceeds the resource limit');
+        uri = new URL(uriInput);
+        const segments = uri.pathname.split('/');
+        if (uri.protocol !== 'hoi4-agent:' ||
+            uri.hostname !== 'workspace' ||
+            segments.length !== 6 ||
+            segments[0] !== '' ||
+            segments[2] !== 'artifact' ||
+            segments.some((segment, index) => index !== 0 && segment === ''))
+            throw new Error('Invalid resource path');
+        workspaceId = decodeURIComponent(segments[1]);
+    }
+    catch {
+        throw new ServiceError('RESOURCE_URI_INVALID', 'Resource URI is invalid');
+    }
+    signal.throwIfAborted();
+    assertResourceSelectors(uri, ['offset', 'length', 'metadata']);
+    const workspace = engine.resolver.get(workspaceId, context.principal);
+    const offset = artifactRangeParameter(uri, 'offset', 0, 0);
+    const length = artifactRangeParameter(uri, 'length', artifactResourceLimit, 1, artifactResourceLimit);
+    const metadata = uri.searchParams.get('metadata');
+    if (metadata !== null && metadata !== 'manifest') {
+        throw new ServiceError('ARTIFACT_METADATA_INVALID', 'Artifact metadata selector is invalid');
+    }
+    if (metadata === 'manifest') {
+        const described = await engine.artifacts.describe(workspace, contentArtifactUri(uri), signal);
+        const { path: artifactPath, ...publicManifest } = described;
+        void artifactPath;
+        const manifestBytes = Buffer.from(`${canonicalJson(publicManifest)}\n`, 'utf8');
+        const start = Math.min(offset, manifestBytes.length);
+        const selected = manifestBytes.subarray(start, Math.min(manifestBytes.length, start + length));
+        const complete = start === 0 && selected.length === manifestBytes.length;
+        const _meta = artifactChunkMetadata(uri, metadata, manifestBytes.length, start, selected.length, length);
+        return {
+            contents: [
+                complete
+                    ? {
+                        uri: uri.href,
+                        mimeType: 'application/json',
+                        text: selected.toString('utf8'),
+                        _meta,
+                    }
+                    : {
+                        uri: uri.href,
+                        mimeType: 'application/json',
+                        blob: selected.toString('base64'),
+                        _meta,
+                    },
+            ],
+        };
+    }
+    const artifact = await engine.artifacts.read(workspace, contentArtifactUri(uri), { offset, length }, signal);
+    const textual = artifact.mimeType.startsWith('text/') ||
+        artifact.mimeType === 'application/json' ||
+        artifact.mimeType === 'image/svg+xml';
+    const start = Math.min(offset, artifact.totalSize);
+    const complete = start === 0 && artifact.bytes.length === artifact.totalSize;
+    const text = textual && complete ? exactUtf8Text(artifact.bytes) : undefined;
+    const _meta = artifactChunkMetadata(uri, metadata, artifact.totalSize, start, artifact.bytes.length, length);
+    return {
+        contents: [
+            text !== undefined
+                ? { uri: uri.href, mimeType: artifact.mimeType, text, _meta }
+                : {
+                    uri: uri.href,
+                    mimeType: artifact.mimeType,
+                    blob: artifact.bytes.toString('base64'),
+                    _meta,
+                },
+        ],
+    };
+}

package/dist/hoi4_agent_tools/core/artifacts.js

@@ -707,17 +707,27 @@ export class ArtifactStore {
     maxBytes;
     maxEntries;
     maxSingleBytes;
+    retention;
     #verifiedContent = new Map();
-    constructor(maxBytes = 536_870_912, maxEntries = 5_000, maxSingleBytes = 134_217_728) {
+    constructor(maxBytes = 536_870_912, maxEntries = 5_000, maxSingleBytes = 134_217_728, retention) {
         this.maxBytes = maxBytes;
         this.maxEntries = maxEntries;
         this.maxSingleBytes = maxSingleBytes;
+        this.retention = retention;
     }
     async pruneForAdmission(workspace, usage, additionalBytes, additionalEntries, protectedManifests, protectedTargets, signal) {
         if (usage.entries + additionalEntries <= this.maxEntries &&
             usage.bytes <= this.maxBytes - additionalBytes) {
             return usage;
         }
+        // Read durable pins while holding the same cross-process publication lock used by
+        // checkpoint commits. A committed frontier cannot disappear between save and resume.
+        for (const uri of (await this.retention?.(workspace, signal)) ?? []) {
+            signal?.throwIfAborted();
+            const { sha256, provenanceHash, name } = this.parseUri(workspace, uri);
+            protectedTargets.add(await containedGeneratedPath(workspace.artifactRoot, sha256.slice(0, 2), sha256, name));
+            protectedManifests.add(await containedGeneratedPath(workspace.artifactRoot, sha256.slice(0, 2), sha256, `${name}.${provenanceHash}.manifest.json`));
+        }
         // Reclaim to a low-water mark so a busy agent workflow does not rescan and evict one artifact
         // for every subsequent tool call. The incoming batch itself remains protected and atomic.
         const targetBytes = Math.max(0, Math.min(this.maxBytes - additionalBytes, Math.floor(this.maxBytes * 0.75)));
@@ -1222,7 +1232,7 @@ export class ArtifactStore {
         if (physicalWrites.length !== admission.projectedEntries) {
             throw new ServiceError('ARTIFACT_STORAGE_LIMIT', 'Artifact batch entry projection did not match prepared output');
         }
-        return this.withAtomicWrites(workspace, physicalWrites, (stored) => commit(logicalIndexes.map((index) => stored[index])), signal);
+        return this.withAtomicWrites(workspace, physicalWrites, (stored) => commit(logicalIndexes.map((index) => stored[index]), stored), signal);
     }
     plannedArtifactLink(workspace, write, bytes, sha256) {
         const manifestWithoutHash = {
@@ -1458,6 +1468,78 @@ export class ArtifactStore {
         await refreshArtifactManifest(manifestPath);
         return { bytes, mimeType: manifest.mimeType, name, totalSize };
     }
+    /** Read either one stored object or an authenticated chunk index as exact logical bytes. */
+    async readLogical(workspace, uri, options, signal) {
+        const initial = await this.read(workspace, uri, undefined, signal);
+        if (initial.mimeType !== options.mimeType)
+            throw new ServiceError('ARTIFACT_LOGICAL_TYPE_MISMATCH', `Logical artifact must use ${options.mimeType}`);
+        let parsed;
+        try {
+            parsed = JSON.parse(initial.bytes.toString('utf8'));
+        }
+        catch {
+            if (initial.totalSize > options.maxBytes)
+                throw new ServiceError('ARTIFACT_LOGICAL_LIMIT', 'Logical artifact exceeds its fixed byte ceiling');
+            return initial;
+        }
+        if (parsed === null ||
+            typeof parsed !== 'object' ||
+            Array.isArray(parsed) ||
+            parsed.type !== 'hoi4-agent.chunked-artifact') {
+            if (initial.totalSize > options.maxBytes)
+                throw new ServiceError('ARTIFACT_LOGICAL_LIMIT', 'Logical artifact exceeds its fixed byte ceiling');
+            return initial;
+        }
+        const index = parsed;
+        if (index.schemaVersion !== 1 ||
+            index.original === undefined ||
+            !Array.isArray(index.chunks) ||
+            index.chunks.length < 1 ||
+            index.chunks.length > options.maxChunks ||
+            index.original.mimeType !== options.mimeType ||
+            !Number.isSafeInteger(index.original.size) ||
+            index.original.size < 0 ||
+            index.original.size > options.maxBytes ||
+            !/^[a-f0-9]{64}$/u.test(index.original.sha256))
+            throw new ServiceError('ARTIFACT_LOGICAL_INVALID', 'Chunked logical artifact index is malformed or exceeds its fixed limits');
+        const buffers = [];
+        const chunkUris = new Set();
+        let offset = 0;
+        for (const [chunkIndex, candidate] of index.chunks.entries()) {
+            signal?.throwIfAborted();
+            if (candidate.index !== chunkIndex ||
+                candidate.offset !== offset ||
+                !Number.isSafeInteger(candidate.length) ||
+                candidate.length <= 0 ||
+                candidate.size !== candidate.length ||
+                candidate.mimeType !== 'application/octet-stream' ||
+                typeof candidate.uri !== 'string' ||
+                chunkUris.has(candidate.uri) ||
+                !/^[a-f0-9]{64}$/u.test(candidate.sha256) ||
+                offset + candidate.length > index.original.size)
+                throw new ServiceError('ARTIFACT_LOGICAL_INVALID', 'Chunked logical artifact entry is malformed');
+            chunkUris.add(candidate.uri);
+            const chunk = await this.read(workspace, candidate.uri, undefined, signal);
+            if (chunk.mimeType !== 'application/octet-stream' ||
+                chunk.totalSize !== candidate.length ||
+                chunk.bytes.length !== candidate.length ||
+                sha256Bytes(chunk.bytes) !== candidate.sha256)
+                throw new ServiceError('ARTIFACT_LOGICAL_INVALID', 'Chunked logical artifact content does not match its authenticated index');
+            buffers.push(chunk.bytes);
+            offset += chunk.bytes.length;
+        }
+        const bytes = Buffer.concat(buffers, index.original.size);
+        if (offset !== index.original.size ||
+            bytes.length !== index.original.size ||
+            sha256Bytes(bytes) !== index.original.sha256)
+            throw new ServiceError('ARTIFACT_LOGICAL_INVALID', 'Chunked logical artifact does not reconstruct its declared content');
+        return {
+            bytes,
+            mimeType: index.original.mimeType,
+            name: index.original.name,
+            totalSize: index.original.size,
+        };
+    }
     uri(workspaceId, sha256, provenanceHash, name) {
         return `hoi4-agent://workspace/${encodeURIComponent(workspaceId)}/artifact/${sha256}/${provenanceHash}/${encodeURIComponent(name)}`;
     }