hoi4-agent-tools 0.0.0-bootstrap.1 → 0.1.3

package/dist/hoi4_agent_tools/core/artifacts.js

@@ -0,0 +1,1047 @@
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, open, readFile, readdir, stat, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod/v4';
+import { canonicalJson, compareCodeUnits, sha256Bytes } from './canonical.js';
+import { ServiceError } from './result.js';
+import { containedGeneratedPath, isPortablePathSegment } from './workspace.js';
+const sha256Schema = z.string().regex(/^[a-f0-9]{64}$/u);
+const artifactProvenanceSchema = z
+    .object({
+    kind: z.string(),
+    toolVersion: z.string(),
+    schemaVersion: z.string(),
+    sourceHashes: z.record(z.string(), sha256Schema),
+    renderProfile: z.record(z.string(), z.unknown()).optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+})
+    .strict();
+const artifactManifestSchema = z
+    .object({
+    version: z.literal(2),
+    workspaceIdentity: sha256Schema,
+    ownerIdentity: sha256Schema,
+    name: z.string(),
+    mimeType: z.string(),
+    size: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    sha256: sha256Schema,
+    provenanceHash: sha256Schema,
+    provenance: artifactProvenanceSchema,
+    description: z.string().optional(),
+})
+    .strict();
+function artifactFileIdentity(value) {
+    return {
+        dev: value.dev,
+        ino: value.ino,
+        size: value.size,
+        mtimeMs: value.mtimeMs,
+        ctimeMs: value.ctimeMs,
+    };
+}
+function sameArtifactIdentity(left, right) {
+    return (left?.dev === right.dev &&
+        left.ino === right.ino &&
+        left.size === right.size &&
+        left.mtimeMs === right.mtimeMs &&
+        left.ctimeMs === right.ctimeMs);
+}
+function provenanceHashFor(manifest) {
+    return sha256Bytes(canonicalJson({
+        version: manifest.version,
+        workspaceIdentity: manifest.workspaceIdentity,
+        ownerIdentity: manifest.ownerIdentity,
+        name: manifest.name,
+        mimeType: manifest.mimeType,
+        size: manifest.size,
+        sha256: manifest.sha256,
+        provenance: manifest.provenance,
+        description: manifest.description ?? null,
+    }));
+}
+function artifactContentBytes(content) {
+    return typeof content === 'string' ? Buffer.from(content, 'utf8') : Buffer.from(content);
+}
+function chunkArtifactName(originalSha256, index) {
+    return `chunk-${originalSha256}-${String(index).padStart(6, '0')}.part`;
+}
+function chunkIndexArtifactName(originalName, originalSha256) {
+    const suffix = `.${originalSha256.slice(0, 16)}.chunks.json`;
+    const prefix = originalName.slice(0, Math.max(1, 128 - suffix.length));
+    return `${prefix}${suffix}`;
+}
+function chunkedProvenance(provenance, role, original, details) {
+    return {
+        ...provenance,
+        kind: `${provenance.kind}-${role}`,
+        metadata: {
+            ...(provenance.metadata ?? {}),
+            chunkedArtifact: {
+                role,
+                originalName: original.name,
+                originalMimeType: original.mimeType,
+                originalSize: original.size,
+                originalSha256: original.sha256,
+                ...details,
+            },
+        },
+    };
+}
+/**
+ * Keep provenance manifests bounded while retaining a deterministic commitment
+ * to every source path/hash pair. Complete inventories remain in domain evidence.
+ */
+export function boundedSourceHashEvidence(sourceHashes) {
+    const entries = Object.entries(sourceHashes).sort(([left], [right]) => compareCodeUnits(left, right));
+    const digest = createHash('sha256');
+    digest.update('source-hash-inventory.v1\0', 'utf8');
+    const retained = [];
+    let retainedBytes = 2;
+    let retainedCount = 0;
+    const maximumRetainedBytes = 131_072;
+    const maximumRetainedEntries = 256;
+    for (const [sourcePath, sourceHash] of entries) {
+        const pathBytes = Buffer.from(sourcePath, 'utf8');
+        digest.update(String(pathBytes.length), 'ascii');
+        digest.update(':', 'ascii');
+        digest.update(pathBytes);
+        digest.update(':', 'ascii');
+        digest.update(sourceHash, 'ascii');
+        digest.update('\n', 'ascii');
+        const entryBytes = Buffer.byteLength(JSON.stringify(sourcePath), 'utf8') +
+            Buffer.byteLength(JSON.stringify(sourceHash), 'utf8') +
+            2;
+        if (retainedCount < maximumRetainedEntries &&
+            retainedBytes + entryBytes <= maximumRetainedBytes) {
+            retained.push([sourcePath, sourceHash]);
+            retainedBytes += entryBytes;
+            retainedCount += 1;
+        }
+    }
+    return {
+        sourceHashes: Object.fromEntries(retained),
+        inventory: {
+            schemaVersion: 1,
+            algorithm: 'sha256-length-prefixed-path-digest-v1',
+            count: entries.length,
+            digest: digest.digest('hex'),
+            retainedCount,
+            truncated: retainedCount !== entries.length,
+        },
+    };
+}
+function assertManifestIntegrity(manifest, expected, workspace) {
+    if (manifest.workspaceIdentity !== workspace.workspaceIdentity ||
+        manifest.ownerIdentity !== workspace.ownerIdentity ||
+        manifest.sha256 !== expected.sha256 ||
+        manifest.provenanceHash !== expected.provenanceHash ||
+        manifest.name !== expected.name ||
+        provenanceHashFor(manifest) !== expected.provenanceHash) {
+        throw new ServiceError('ARTIFACT_MANIFEST_INTEGRITY_FAILED', 'Artifact provenance manifest does not match its immutable address');
+    }
+}
+/** Return the only artifact fields that may cross the MCP trust boundary. */
+export function publicArtifactLink(artifact) {
+    return {
+        uri: artifact.uri,
+        name: artifact.name,
+        mimeType: artifact.mimeType,
+        ...(artifact.size === undefined ? {} : { size: artifact.size }),
+        ...(artifact.sha256 === undefined ? {} : { sha256: artifact.sha256 }),
+        ...(artifact.description === undefined ? {} : { description: artifact.description }),
+    };
+}
+const safeNamePattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+const reservedManifestSuffix = '.manifest.json';
+const artifactReadBufferBytes = 1_048_576;
+const artifactPageMaxEntries = 100;
+const artifactManifestMaxBytes = 1_048_576;
+const artifactLogicalBatchMaxBytes = 536_870_912;
+const artifactHashYieldBytes = 16_777_216;
+const artifactPreflightYieldEntries = 256;
+const ownedArtifactContent = Symbol('ownedArtifactContent');
+const precomputedArtifactSha256 = Symbol('precomputedArtifactSha256');
+export const chunkedArtifactIndexMimeType = 'application/json';
+function isValidArtifactName(name) {
+    return (safeNamePattern.test(name) &&
+        isPortablePathSegment(name) &&
+        !name.toLowerCase().endsWith(reservedManifestSuffix));
+}
+function artifactContentByteLength(content) {
+    return typeof content === 'string' ? Buffer.byteLength(content, 'utf8') : content.byteLength;
+}
+async function preflightArtifactBatch(writes, limits, signal) {
+    const { maxBytes, maxEntries, maxSingleBytes, chunked } = limits;
+    if (!Number.isSafeInteger(maxBytes) ||
+        maxBytes < 1 ||
+        !Number.isSafeInteger(maxEntries) ||
+        maxEntries < 1 ||
+        !Number.isSafeInteger(maxSingleBytes) ||
+        maxSingleBytes < 1 ||
+        maxSingleBytes > maxBytes) {
+        throw new ServiceError('ARTIFACT_STORAGE_LIMIT', 'Configured artifact limits are invalid');
+    }
+    const contentLengths = [];
+    let totalBytes = 0;
+    let projectedEntries = 0;
+    for (const [writeIndex, write] of writes.entries()) {
+        signal?.throwIfAborted();
+        if (!isValidArtifactName(write.name)) {
+            throw new ServiceError('ARTIFACT_NAME_INVALID', `Invalid artifact name: ${write.name}`);
+        }
+        if (!artifactProvenanceSchema.safeParse(write.provenance).success) {
+            throw new ServiceError('ARTIFACT_PROVENANCE_INVALID', 'Artifact provenance must contain only valid SHA-256 source hashes');
+        }
+        const contentLength = artifactContentByteLength(write.content);
+        if (!Number.isSafeInteger(contentLength) || contentLength < 0) {
+            throw new ServiceError('ARTIFACT_STORAGE_LIMIT', 'Artifact content byte length is unsafe', {
+                name: write.name,
+            });
+        }
+        if (!chunked && contentLength > maxSingleBytes) {
+            throw new ServiceError('ARTIFACT_SINGLE_LIMIT', 'Artifact exceeds the configured per-artifact byte limit', {
+                name: write.name,
+                mimeType: write.mimeType,
+                size: contentLength,
+                maximumBytes: maxSingleBytes,
+            });
+        }
+        contentLengths.push(contentLength);
+        totalBytes += contentLength;
+        const entriesForWrite = chunked && contentLength > maxSingleBytes ? Math.ceil(contentLength / maxSingleBytes) + 1 : 1;
+        projectedEntries += entriesForWrite;
+        if (!Number.isSafeInteger(totalBytes) || !Number.isSafeInteger(projectedEntries)) {
+            throw new ServiceError('ARTIFACT_STORAGE_LIMIT', 'Artifact batch size is unsafe');
+        }
+        if ((writeIndex + 1) % artifactPreflightYieldEntries === 0) {
+            await new Promise((resolve) => setImmediate(resolve));
+            signal?.throwIfAborted();
+        }
+    }
+    const preparationCeiling = Math.min(maxBytes, artifactLogicalBatchMaxBytes);
+    if (totalBytes > preparationCeiling) {
+        const fixedCeilingApplies = artifactLogicalBatchMaxBytes <= maxBytes;
+        throw new ServiceError(fixedCeilingApplies ? 'ARTIFACT_LOGICAL_BATCH_LIMIT' : 'ARTIFACT_STORAGE_LIMIT', fixedCeilingApplies
+            ? 'Logical artifact batch exceeds the fixed in-memory preparation ceiling'
+            : 'Logical artifact batch exceeds the configured aggregate artifact-byte limit', { size: totalBytes, maximumBytes: preparationCeiling });
+    }
+    if (projectedEntries > maxEntries) {
+        throw new ServiceError('ARTIFACT_STORAGE_LIMIT', 'Artifact batch exceeds the configured artifact-entry limit', { projectedEntries, maximumEntries: maxEntries });
+    }
+    signal?.throwIfAborted();
+    return { contentLengths, totalBytes, projectedEntries };
+}
+async function sha256BytesWithSignal(bytes, signal) {
+    signal?.throwIfAborted();
+    const hash = createHash('sha256');
+    for (let offset = 0; offset < bytes.length; offset += artifactHashYieldBytes) {
+        hash.update(bytes.subarray(offset, Math.min(bytes.length, offset + artifactHashYieldBytes)));
+        if (offset + artifactHashYieldBytes < bytes.length) {
+            await new Promise((resolve) => setImmediate(resolve));
+            signal?.throwIfAborted();
+        }
+    }
+    signal?.throwIfAborted();
+    return hash.digest('hex');
+}
+function manifestAddressSortKey(fileName) {
+    const matched = /^(.*)\.([a-f0-9]{64})\.manifest\.json$/u.exec(fileName);
+    return matched === null ? fileName : `${matched[2]}/${encodeURIComponent(matched[1])}`;
+}
+async function fileExists(filePath) {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+const artifactQueues = new Map();
+async function waitForArtifactTurn(previous, signal) {
+    signal?.throwIfAborted();
+    if (signal === undefined) {
+        await previous;
+        return;
+    }
+    let abort;
+    const aborted = new Promise((_resolve, reject) => {
+        abort = () => {
+            reject(new DOMException('The operation was aborted', 'AbortError'));
+        };
+        signal.addEventListener('abort', abort, { once: true });
+    });
+    try {
+        await Promise.race([previous, aborted]);
+    }
+    finally {
+        signal.removeEventListener('abort', abort);
+    }
+    signal.throwIfAborted();
+}
+async function withArtifactQueue(root, action, signal) {
+    const previous = artifactQueues.get(root) ?? Promise.resolve();
+    let release;
+    const gate = new Promise((resolve) => {
+        release = resolve;
+    });
+    const tail = previous.then(() => gate);
+    artifactQueues.set(root, tail);
+    try {
+        await waitForArtifactTurn(previous, signal);
+        return await action();
+    }
+    finally {
+        release();
+        void tail.then(() => {
+            if (artifactQueues.get(root) === tail)
+                artifactQueues.delete(root);
+        });
+    }
+}
+async function artifactUsage(root, signal) {
+    let bytes = 0;
+    let entries = 0;
+    const walk = async (directory) => {
+        signal?.throwIfAborted();
+        let children;
+        try {
+            children = await readdir(directory, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        for (const child of children) {
+            signal?.throwIfAborted();
+            if (child.isSymbolicLink()) {
+                throw new ServiceError('ARTIFACT_STORAGE_UNSAFE', 'Artifact storage contains a symbolic link or junction');
+            }
+            const candidate = await containedGeneratedPath(root, path.relative(root, path.join(directory, child.name)));
+            if (child.isDirectory())
+                await walk(candidate);
+            else if (child.isFile()) {
+                bytes += (await stat(candidate)).size;
+                if (child.name.endsWith('.manifest.json'))
+                    entries += 1;
+                if (!Number.isSafeInteger(bytes)) {
+                    throw new ServiceError('ARTIFACT_STORAGE_LIMIT', 'Artifact storage size is unsafe');
+                }
+            }
+        }
+    };
+    await walk(await containedGeneratedPath(root));
+    return { bytes, entries };
+}
+async function readArtifactManifest(filePath, signal) {
+    signal?.throwIfAborted();
+    let metadata;
+    try {
+        metadata = await lstat(filePath);
+    }
+    catch {
+        throw new ServiceError('ARTIFACT_NOT_FOUND', 'Artifact provenance manifest is unavailable');
+    }
+    signal?.throwIfAborted();
+    if (metadata.isSymbolicLink() || !metadata.isFile()) {
+        throw new ServiceError('ARTIFACT_MANIFEST_INVALID', 'Artifact provenance manifest is invalid');
+    }
+    if (metadata.size > artifactManifestMaxBytes) {
+        throw new ServiceError('ARTIFACT_MANIFEST_LIMIT', 'Artifact provenance manifest exceeds its fixed byte limit');
+    }
+    let text;
+    try {
+        text =
+            signal === undefined
+                ? await readFile(filePath, 'utf8')
+                : await readFile(filePath, { encoding: 'utf8', signal });
+    }
+    catch (error) {
+        if (error.name === 'AbortError')
+            throw error;
+        throw new ServiceError('ARTIFACT_NOT_FOUND', 'Artifact provenance manifest is unavailable');
+    }
+    signal?.throwIfAborted();
+    try {
+        const validated = artifactManifestSchema.safeParse(JSON.parse(text));
+        if (!validated.success)
+            throw new Error('invalid artifact manifest');
+        return validated.data;
+    }
+    catch {
+        throw new ServiceError('ARTIFACT_MANIFEST_INVALID', 'Artifact provenance manifest is invalid');
+    }
+}
+async function readVerifiedArtifactRange(filePath, expectedSha256, range, verifiedIdentity, signal) {
+    signal?.throwIfAborted();
+    if (range !== undefined &&
+        (!Number.isSafeInteger(range.offset) ||
+            range.offset < 0 ||
+            !Number.isSafeInteger(range.length) ||
+            range.length < 1)) {
+        throw new ServiceError('ARTIFACT_RANGE_INVALID', 'Artifact byte range is invalid');
+    }
+    let handle;
+    try {
+        handle = await open(filePath, 'r');
+    }
+    catch {
+        throw new ServiceError('ARTIFACT_NOT_FOUND', 'Artifact content is unavailable');
+    }
+    try {
+        signal?.throwIfAborted();
+        const beforeIdentity = artifactFileIdentity(await handle.stat());
+        const totalSize = beforeIdentity.size;
+        const offset = range === undefined ? 0 : Math.min(totalSize, range.offset);
+        const requestedLength = range === undefined ? totalSize - offset : Math.min(range.length, artifactReadBufferBytes);
+        const selectedLength = Math.min(requestedLength, totalSize - offset);
+        const selected = Buffer.allocUnsafe(selectedLength);
+        if (sameArtifactIdentity(verifiedIdentity, beforeIdentity)) {
+            let selectedPosition = 0;
+            while (selectedPosition < selectedLength) {
+                signal?.throwIfAborted();
+                const { bytesRead } = await handle.read(selected, selectedPosition, selectedLength - selectedPosition, offset + selectedPosition);
+                if (bytesRead === 0) {
+                    throw new ServiceError('ARTIFACT_READ_INCOMPLETE', 'Artifact content changed while reading');
+                }
+                selectedPosition += bytesRead;
+            }
+        }
+        else {
+            const scratch = Buffer.allocUnsafe(Math.min(artifactReadBufferBytes, Math.max(1, totalSize)));
+            const hash = createHash('sha256');
+            let position = 0;
+            while (position < totalSize) {
+                signal?.throwIfAborted();
+                const requested = Math.min(scratch.length, totalSize - position);
+                const { bytesRead } = await handle.read(scratch, 0, requested, position);
+                if (bytesRead === 0) {
+                    throw new ServiceError('ARTIFACT_READ_INCOMPLETE', 'Artifact content changed while reading');
+                }
+                const chunk = scratch.subarray(0, bytesRead);
+                hash.update(chunk);
+                const chunkEnd = position + bytesRead;
+                const selectionEnd = offset + selectedLength;
+                const overlapStart = Math.max(position, offset);
+                const overlapEnd = Math.min(chunkEnd, selectionEnd);
+                if (overlapStart < overlapEnd) {
+                    chunk.copy(selected, overlapStart - offset, overlapStart - position, overlapEnd - position);
+                }
+                position = chunkEnd;
+            }
+            if (hash.digest('hex') !== expectedSha256) {
+                throw new ServiceError('ARTIFACT_INTEGRITY_FAILED', 'Artifact hash does not match its URI');
+            }
+        }
+        signal?.throwIfAborted();
+        const afterIdentity = artifactFileIdentity(await handle.stat());
+        if (!sameArtifactIdentity(beforeIdentity, afterIdentity)) {
+            throw new ServiceError('ARTIFACT_READ_INCOMPLETE', 'Artifact content changed while reading');
+        }
+        return { bytes: selected, totalSize, identity: afterIdentity };
+    }
+    catch (error) {
+        if (error instanceof ServiceError || error.name === 'AbortError')
+            throw error;
+        throw new ServiceError('ARTIFACT_READ_FAILED', 'Artifact content could not be read');
+    }
+    finally {
+        await handle.close();
+    }
+}
+export class ArtifactStore {
+    maxBytes;
+    maxEntries;
+    maxSingleBytes;
+    #verifiedContent = new Map();
+    constructor(maxBytes = 536_870_912, maxEntries = 5_000, maxSingleBytes = 134_217_728) {
+        this.maxBytes = maxBytes;
+        this.maxEntries = maxEntries;
+        this.maxSingleBytes = maxSingleBytes;
+    }
+    async list(workspace, signal) {
+        signal?.throwIfAborted();
+        const usage = await artifactUsage(workspace.artifactRoot, signal);
+        if (usage.bytes > this.maxBytes || usage.entries > this.maxEntries) {
+            throw new ServiceError('ARTIFACT_STORAGE_LIMIT', 'Artifact storage exceeds the configured retention budget');
+        }
+        const results = [];
+        const walk = async (directory) => {
+            signal?.throwIfAborted();
+            let entries;
+            try {
+                entries = await readdir(directory, { withFileTypes: true });
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    return;
+                throw error;
+            }
+            for (const entry of entries.sort((a, b) => compareCodeUnits(a.name, b.name))) {
+                signal?.throwIfAborted();
+                const candidate = path.join(directory, entry.name);
+                if (entry.isDirectory()) {
+                    await walk(await containedGeneratedPath(workspace.artifactRoot, path.relative(workspace.artifactRoot, candidate)));
+                }
+                else if (entry.isFile() && entry.name.endsWith('.manifest.json')) {
+                    const manifest = await readArtifactManifest(await containedGeneratedPath(workspace.artifactRoot, path.relative(workspace.artifactRoot, candidate)), signal);
+                    if (entry.name !== `${manifest.name}.${manifest.provenanceHash}.manifest.json`) {
+                        throw new ServiceError('ARTIFACT_MANIFEST_INTEGRITY_FAILED', 'Artifact provenance manifest filename does not match its contents');
+                    }
+                    assertManifestIntegrity(manifest, {
+                        sha256: path.basename(directory),
+                        provenanceHash: manifest.provenanceHash,
+                        name: manifest.name,
+                    }, workspace);
+                    results.push({
+                        uri: this.uri(workspace.id, manifest.sha256, manifest.provenanceHash, manifest.name),
+                        name: manifest.name,
+                        mimeType: manifest.mimeType,
+                        size: manifest.size,
+                        sha256: manifest.sha256,
+                        ...(manifest.description === undefined ? {} : { description: manifest.description }),
+                    });
+                }
+            }
+        };
+        await walk(await containedGeneratedPath(workspace.artifactRoot));
+        return results.sort((a, b) => compareCodeUnits(a.uri, b.uri));
+    }
+    async listPage(workspace, options, signal) {
+        signal?.throwIfAborted();
+        if (!Number.isSafeInteger(options.limit) ||
+            options.limit < 1 ||
+            options.limit > artifactPageMaxEntries) {
+            throw new ServiceError('ARTIFACT_PAGE_INVALID', `Artifact page limit must be between 1 and ${artifactPageMaxEntries}`);
+        }
+        const usage = await artifactUsage(workspace.artifactRoot, signal);
+        if (usage.bytes > this.maxBytes || usage.entries > this.maxEntries) {
+            throw new ServiceError('ARTIFACT_STORAGE_LIMIT', 'Artifact storage exceeds the configured retention budget');
+        }
+        const artifacts = [];
+        const revision = createHash('sha256');
+        let total = 0;
+        let afterFound = options.afterUri === undefined;
+        let hasMore = false;
+        const visitManifest = async (directory, entryName) => {
+            signal?.throwIfAborted();
+            const manifest = await readArtifactManifest(await containedGeneratedPath(workspace.artifactRoot, path.relative(workspace.artifactRoot, path.join(directory, entryName))), signal);
+            if (entryName !== `${manifest.name}.${manifest.provenanceHash}.manifest.json`) {
+                throw new ServiceError('ARTIFACT_MANIFEST_INTEGRITY_FAILED', 'Artifact provenance manifest filename does not match its contents');
+            }
+            assertManifestIntegrity(manifest, {
+                sha256: path.basename(directory),
+                provenanceHash: manifest.provenanceHash,
+                name: manifest.name,
+            }, workspace);
+            const uri = this.uri(workspace.id, manifest.sha256, manifest.provenanceHash, manifest.name);
+            revision.update(`${Buffer.byteLength(uri, 'utf8')}:${uri}`);
+            total += 1;
+            if (!afterFound) {
+                if (uri === options.afterUri)
+                    afterFound = true;
+                return;
+            }
+            if (artifacts.length < options.limit) {
+                artifacts.push({
+                    uri,
+                    name: manifest.name,
+                    mimeType: manifest.mimeType,
+                    size: manifest.size,
+                    sha256: manifest.sha256,
+                    ...(manifest.description === undefined ? {} : { description: manifest.description }),
+                });
+            }
+            else {
+                hasMore = true;
+            }
+        };
+        const walk = async (directory) => {
+            signal?.throwIfAborted();
+            let entries;
+            try {
+                entries = await readdir(directory, { withFileTypes: true });
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    return;
+                throw error;
+            }
+            for (const entry of entries
+                .filter((candidate) => candidate.isDirectory())
+                .sort((left, right) => compareCodeUnits(left.name, right.name))) {
+                signal?.throwIfAborted();
+                await walk(await containedGeneratedPath(workspace.artifactRoot, path.relative(workspace.artifactRoot, path.join(directory, entry.name))));
+            }
+            for (const entry of entries
+                .filter((candidate) => candidate.isFile() && candidate.name.endsWith('.manifest.json'))
+                .sort((left, right) => compareCodeUnits(manifestAddressSortKey(left.name), manifestAddressSortKey(right.name)))) {
+                await visitManifest(directory, entry.name);
+            }
+        };
+        await walk(await containedGeneratedPath(workspace.artifactRoot));
+        return {
+            artifacts,
+            total,
+            revision: revision.digest('hex'),
+            afterFound,
+            hasMore,
+        };
+    }
+    async describe(workspace, uri, signal) {
+        signal?.throwIfAborted();
+        const parsed = this.parseUri(workspace, uri);
+        const target = await containedGeneratedPath(workspace.artifactRoot, parsed.sha256.slice(0, 2), parsed.sha256, `${parsed.name}.${parsed.provenanceHash}.manifest.json`);
+        const manifest = await readArtifactManifest(target, signal);
+        assertManifestIntegrity(manifest, parsed, workspace);
+        return {
+            uri,
+            name: manifest.name,
+            mimeType: manifest.mimeType,
+            size: manifest.size,
+            sha256: manifest.sha256,
+            provenanceHash: manifest.provenanceHash,
+            provenance: manifest.provenance,
+            ...(manifest.description === undefined ? {} : { description: manifest.description }),
+            path: await containedGeneratedPath(workspace.artifactRoot, parsed.sha256.slice(0, 2), parsed.sha256, parsed.name),
+        };
+    }
+    async put(workspace, name, mimeType, content, provenance, description, signal) {
+        return this.withAtomicWrites(workspace, [
+            {
+                name,
+                mimeType,
+                content,
+                provenance,
+                ...(description === undefined ? {} : { description }),
+            },
+        ], ([artifact]) => {
+            if (artifact === undefined)
+                throw new Error('Artifact batch returned no result');
+            return Promise.resolve(artifact);
+        }, signal);
+    }
+    /**
+     * Store one logical artifact without weakening the configured per-object limit.
+     * Oversized content is represented by a canonical JSON index whose ordered
+     * resource links reconstruct the exact original bytes.
+     */
+    async putChunked(workspace, name, mimeType, content, provenance, description, signal) {
+        return this.withAtomicChunkedWrites(workspace, [
+            {
+                name,
+                mimeType,
+                content,
+                provenance,
+                ...(description === undefined ? {} : { description }),
+            },
+        ], ([artifact]) => {
+            if (artifact === undefined)
+                throw new Error('Artifact batch returned no result');
+            return Promise.resolve(artifact);
+        }, signal);
+    }
+    /**
+     * Persist logical artifacts as one failure boundary. Every small write maps to
+     * one normal artifact. Every oversized write maps to an index plus bounded
+     * content chunks, while the callback receives only the logical normal/index
+     * artifacts in the caller's original order.
+     */
+    async withAtomicChunkedWrites(workspace, writes, commit, signal) {
+        signal?.throwIfAborted();
+        const admission = await preflightArtifactBatch(writes, {
+            maxBytes: this.maxBytes,
+            maxEntries: this.maxEntries,
+            maxSingleBytes: this.maxSingleBytes,
+            chunked: true,
+        }, signal);
+        const physicalWrites = [];
+        const logicalIndexes = [];
+        for (const [writeIndex, write] of writes.entries()) {
+            signal?.throwIfAborted();
+            const expectedLength = admission.contentLengths[writeIndex];
+            const bytes = artifactContentBytes(write.content);
+            if (bytes.length !== expectedLength) {
+                throw new ServiceError('ARTIFACT_CONTENT_CHANGED', 'Artifact content length changed after batch admission', { name: write.name, expectedLength, actualLength: bytes.length });
+            }
+            signal?.throwIfAborted();
+            if (bytes.length <= this.maxSingleBytes) {
+                const sha256 = await sha256BytesWithSignal(bytes, signal);
+                logicalIndexes.push(physicalWrites.length);
+                physicalWrites.push({
+                    ...write,
+                    content: bytes,
+                    [ownedArtifactContent]: true,
+                    [precomputedArtifactSha256]: sha256,
+                });
+                continue;
+            }
+            const originalSha256 = await sha256BytesWithSignal(bytes, signal);
+            const original = {
+                name: write.name,
+                mimeType: write.mimeType,
+                size: bytes.length,
+                sha256: originalSha256,
+            };
+            const chunkCount = Math.ceil(bytes.length / this.maxSingleBytes);
+            const chunks = [];
+            for (let index = 0; index < chunkCount; index += 1) {
+                signal?.throwIfAborted();
+                const offset = index * this.maxSingleBytes;
+                const content = bytes.subarray(offset, Math.min(bytes.length, offset + this.maxSingleBytes));
+                const name = chunkArtifactName(originalSha256, index);
+                const provenance = chunkedProvenance(write.provenance, 'chunk', original, {
+                    chunkIndex: index,
+                    chunkCount,
+                    offset,
+                    length: content.length,
+                });
+                const chunkSha256 = await sha256BytesWithSignal(content, signal);
+                const chunkWrite = {
+                    name,
+                    mimeType: 'application/octet-stream',
+                    content,
+                    provenance,
+                    description: `Byte-exact chunk ${index + 1} of ${chunkCount} for ${write.name}`,
+                    [ownedArtifactContent]: true,
+                    [precomputedArtifactSha256]: chunkSha256,
+                };
+                const planned = this.plannedArtifactLink(workspace, chunkWrite, content, chunkSha256);
+                chunks.push({
+                    index,
+                    offset,
+                    length: content.length,
+                    uri: planned.uri,
+                    name: planned.name,
+                    mimeType: 'application/octet-stream',
+                    size: content.length,
+                    sha256: planned.sha256,
+                });
+                physicalWrites.push(chunkWrite);
+            }
+            const indexDocument = {
+                schemaVersion: 1,
+                type: 'hoi4-agent.chunked-artifact',
+                original: {
+                    ...original,
+                    ...(write.description === undefined ? {} : { description: write.description }),
+                },
+                chunks,
+            };
+            const indexContent = Buffer.from(`${canonicalJson(indexDocument)}\n`, 'utf8');
+            if (indexContent.length > this.maxSingleBytes ||
+                indexContent.length > artifactManifestMaxBytes) {
+                throw new ServiceError('ARTIFACT_CHUNK_INDEX_LIMIT', 'Chunked artifact index exceeds its fixed single-resource byte limit', {
+                    name: write.name,
+                    size: indexContent.length,
+                    maximumBytes: Math.min(this.maxSingleBytes, artifactManifestMaxBytes),
+                });
+            }
+            const indexSha256 = await sha256BytesWithSignal(indexContent, signal);
+            const indexWrite = {
+                name: chunkIndexArtifactName(write.name, originalSha256),
+                mimeType: chunkedArtifactIndexMimeType,
+                content: indexContent,
+                provenance: chunkedProvenance(write.provenance, 'index', original, {
+                    chunkCount,
+                    indexSchemaVersion: 1,
+                }),
+                description: write.description === undefined
+                    ? `Byte-exact chunk index for ${write.name}`
+                    : `${write.description} (byte-exact chunk index)`,
+                [ownedArtifactContent]: true,
+                [precomputedArtifactSha256]: indexSha256,
+            };
+            logicalIndexes.push(physicalWrites.length);
+            physicalWrites.push(indexWrite);
+        }
+        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);
+    }
+    plannedArtifactLink(workspace, write, bytes, sha256) {
+        const manifestWithoutHash = {
+            version: 2,
+            workspaceIdentity: workspace.workspaceIdentity,
+            ownerIdentity: workspace.ownerIdentity,
+            name: write.name,
+            mimeType: write.mimeType,
+            size: bytes.length,
+            sha256,
+            provenance: write.provenance,
+            ...(write.description === undefined ? {} : { description: write.description }),
+        };
+        const provenanceHash = provenanceHashFor(manifestWithoutHash);
+        return {
+            uri: this.uri(workspace.id, sha256, provenanceHash, write.name),
+            name: write.name,
+            mimeType: write.mimeType,
+            size: bytes.length,
+            sha256,
+            ...(write.description === undefined ? {} : { description: write.description }),
+        };
+    }
+    /**
+     * Persist a set of immutable artifacts as one failure boundary. Files created by
+     * this batch are removed if preparation, storage admission, a write, or the
+     * caller's commit callback fails. Pre-existing content or provenance manifests
+     * are never removed, so rollback remains safe when artifacts are shared.
+     */
+    async withAtomicWrites(workspace, writes, commit, signal) {
+        signal?.throwIfAborted();
+        const admission = await preflightArtifactBatch(writes, {
+            maxBytes: this.maxBytes,
+            maxEntries: this.maxEntries,
+            maxSingleBytes: this.maxSingleBytes,
+            chunked: false,
+        }, signal);
+        const prepared = [];
+        for (const [writeIndex, write] of writes.entries()) {
+            const { name, mimeType, content, provenance, description } = write;
+            const internal = write;
+            signal?.throwIfAborted();
+            const bytes = internal[ownedArtifactContent] === true && Buffer.isBuffer(content)
+                ? content
+                : artifactContentBytes(content);
+            const expectedLength = admission.contentLengths[writeIndex];
+            if (bytes.length !== expectedLength) {
+                throw new ServiceError('ARTIFACT_CONTENT_CHANGED', 'Artifact content length changed after batch admission', { name, expectedLength, actualLength: bytes.length });
+            }
+            signal?.throwIfAborted();
+            const sha256 = internal[precomputedArtifactSha256] ?? (await sha256BytesWithSignal(bytes, signal));
+            if (!/^[a-f0-9]{64}$/u.test(sha256)) {
+                throw new ServiceError('ARTIFACT_HASH_INVALID', 'Precomputed artifact hash is invalid');
+            }
+            signal?.throwIfAborted();
+            const manifestWithoutHash = {
+                version: 2,
+                workspaceIdentity: workspace.workspaceIdentity,
+                ownerIdentity: workspace.ownerIdentity,
+                name,
+                mimeType,
+                size: bytes.length,
+                sha256,
+                provenance,
+                ...(description === undefined ? {} : { description }),
+            };
+            const provenanceHash = provenanceHashFor(manifestWithoutHash);
+            const manifest = { ...manifestWithoutHash, provenanceHash };
+            const manifestBytes = `${canonicalJson(manifest)}\n`;
+            if (Buffer.byteLength(manifestBytes, 'utf8') > this.maxSingleBytes ||
+                Buffer.byteLength(manifestBytes, 'utf8') > artifactManifestMaxBytes) {
+                throw new ServiceError('ARTIFACT_MANIFEST_LIMIT', 'Artifact provenance exceeds its fixed manifest byte limit');
+            }
+            const directory = await containedGeneratedPath(workspace.artifactRoot, sha256.slice(0, 2), sha256);
+            const target = await containedGeneratedPath(workspace.artifactRoot, sha256.slice(0, 2), sha256, name);
+            const manifestPath = await containedGeneratedPath(workspace.artifactRoot, sha256.slice(0, 2), sha256, `${name}.${provenanceHash}.manifest.json`);
+            signal?.throwIfAborted();
+            const artifact = {
+                uri: this.uri(workspace.id, sha256, provenanceHash, name),
+                name,
+                mimeType,
+                size: bytes.length,
+                sha256,
+                provenanceHash,
+                ...(description === undefined ? {} : { description }),
+                path: target,
+                provenance,
+            };
+            prepared.push({ artifact, bytes, directory, target, manifestPath, manifestBytes });
+        }
+        return withArtifactQueue(workspace.artifactRoot, async () => {
+            signal?.throwIfAborted();
+            const uniqueTargets = new Map();
+            const uniqueManifests = new Map();
+            for (const artifact of prepared) {
+                signal?.throwIfAborted();
+                const duplicateTarget = uniqueTargets.get(artifact.target);
+                if (duplicateTarget !== undefined && !duplicateTarget.bytes.equals(artifact.bytes)) {
+                    throw new ServiceError('ARTIFACT_HASH_COLLISION', 'Artifact batch maps different bytes to the same content path');
+                }
+                if (duplicateTarget === undefined) {
+                    const exists = await fileExists(artifact.target);
+                    signal?.throwIfAborted();
+                    if (exists) {
+                        const verificationKey = `${workspace.workspaceIdentity}\0${workspace.ownerIdentity}\0${artifact.target}\0${artifact.artifact.sha256}`;
+                        try {
+                            const verified = await readVerifiedArtifactRange(artifact.target, artifact.artifact.sha256, { offset: 0, length: 1 }, this.#verifiedContent.get(verificationKey), signal);
+                            this.#verifiedContent.set(verificationKey, verified.identity);
+                        }
+                        catch (error) {
+                            if (error.name === 'AbortError')
+                                throw error;
+                            throw new ServiceError('ARTIFACT_HASH_COLLISION', 'Artifact path contains different bytes');
+                        }
+                    }
+                    uniqueTargets.set(artifact.target, { ...artifact, exists });
+                }
+                const duplicateManifest = uniqueManifests.get(artifact.manifestPath);
+                if (duplicateManifest !== undefined &&
+                    duplicateManifest.manifestBytes !== artifact.manifestBytes) {
+                    throw new ServiceError('ARTIFACT_MANIFEST_INTEGRITY_FAILED', 'Artifact batch maps different provenance to the same immutable manifest');
+                }
+                if (duplicateManifest === undefined) {
+                    const exists = await fileExists(artifact.manifestPath);
+                    signal?.throwIfAborted();
+                    if (exists &&
+                        `${canonicalJson(await readArtifactManifest(artifact.manifestPath, signal))}\n` !==
+                            artifact.manifestBytes) {
+                        throw new ServiceError('ARTIFACT_MANIFEST_INTEGRITY_FAILED', 'Immutable artifact provenance manifest contains different bytes');
+                    }
+                    uniqueManifests.set(artifact.manifestPath, { ...artifact, exists });
+                }
+            }
+            const additionalBytes = [...uniqueTargets.values()].reduce((total, artifact) => total + (artifact.exists ? 0 : artifact.bytes.length), 0) +
+                [...uniqueManifests.values()].reduce((total, artifact) => total + (artifact.exists ? 0 : Buffer.byteLength(artifact.manifestBytes, 'utf8')), 0);
+            if (!Number.isSafeInteger(additionalBytes)) {
+                throw new ServiceError('ARTIFACT_STORAGE_LIMIT', 'Artifact batch size is unsafe');
+            }
+            const usage = await artifactUsage(workspace.artifactRoot, signal);
+            const additionalEntries = [...uniqueManifests.values()].filter((artifact) => !artifact.exists).length;
+            if (usage.entries + additionalEntries > this.maxEntries ||
+                usage.bytes > this.maxBytes - additionalBytes) {
+                throw new ServiceError('ARTIFACT_STORAGE_LIMIT', 'Artifact storage retention limit has been reached');
+            }
+            const createdTargets = [];
+            const createdManifests = [];
+            try {
+                for (const artifact of uniqueTargets.values()) {
+                    signal?.throwIfAborted();
+                    if (artifact.exists)
+                        continue;
+                    await mkdir(artifact.directory, { recursive: true });
+                    signal?.throwIfAborted();
+                    try {
+                        await writeFile(artifact.target, artifact.bytes, {
+                            flag: 'wx',
+                            ...(signal === undefined ? {} : { signal }),
+                        });
+                        createdTargets.push(artifact.target);
+                    }
+                    catch (error) {
+                        if (error.code !== 'EEXIST') {
+                            createdTargets.push(artifact.target);
+                        }
+                        throw error;
+                    }
+                }
+                for (const artifact of uniqueManifests.values()) {
+                    signal?.throwIfAborted();
+                    if (artifact.exists)
+                        continue;
+                    await mkdir(artifact.directory, { recursive: true });
+                    signal?.throwIfAborted();
+                    try {
+                        await writeFile(artifact.manifestPath, artifact.manifestBytes, {
+                            flag: 'wx',
+                            ...(signal === undefined ? {} : { signal }),
+                        });
+                        createdManifests.push(artifact.manifestPath);
+                    }
+                    catch (error) {
+                        if (error.code !== 'EEXIST') {
+                            createdManifests.push(artifact.manifestPath);
+                        }
+                        throw error;
+                    }
+                }
+                signal?.throwIfAborted();
+                // The caller's commit callback is the ownership boundary. Once entered,
+                // it completes or fails under its own critical-phase rules; a late abort
+                // cannot make the store remove evidence already committed elsewhere.
+                return await commit(prepared.map(({ artifact }) => artifact));
+            }
+            catch (error) {
+                let cleanupFailed = false;
+                for (const manifestPath of createdManifests.reverse()) {
+                    try {
+                        await unlink(manifestPath);
+                    }
+                    catch (cleanupError) {
+                        if (cleanupError.code !== 'ENOENT')
+                            cleanupFailed = true;
+                    }
+                }
+                for (const target of createdTargets.reverse()) {
+                    try {
+                        const prefix = `${path.basename(target)}.`;
+                        const hasManifest = (await readdir(path.dirname(target), { withFileTypes: true })).some((entry) => entry.isFile() &&
+                            entry.name.startsWith(prefix) &&
+                            entry.name.endsWith('.manifest.json'));
+                        if (!hasManifest) {
+                            await unlink(target);
+                            const verificationPrefix = `${workspace.workspaceIdentity}\0${workspace.ownerIdentity}\0${target}\0`;
+                            for (const key of this.#verifiedContent.keys()) {
+                                if (key.startsWith(verificationPrefix))
+                                    this.#verifiedContent.delete(key);
+                            }
+                        }
+                    }
+                    catch (cleanupError) {
+                        if (cleanupError.code !== 'ENOENT')
+                            cleanupFailed = true;
+                    }
+                }
+                if (cleanupFailed) {
+                    throw new ServiceError('ARTIFACT_BATCH_ROLLBACK_FAILED', 'Artifact batch failed and its newly created files could not all be removed');
+                }
+                throw error;
+            }
+        }, signal);
+    }
+    async read(workspace, uri, range, signal) {
+        signal?.throwIfAborted();
+        const { sha256, provenanceHash, name } = this.parseUri(workspace, uri);
+        const target = await containedGeneratedPath(workspace.artifactRoot, sha256.slice(0, 2), sha256, name);
+        const manifestPath = await containedGeneratedPath(workspace.artifactRoot, sha256.slice(0, 2), sha256, `${name}.${provenanceHash}.manifest.json`);
+        const manifest = await readArtifactManifest(manifestPath, signal);
+        assertManifestIntegrity(manifest, { sha256, provenanceHash, name }, workspace);
+        const verificationKey = `${workspace.workspaceIdentity}\0${workspace.ownerIdentity}\0${target}\0${sha256}`;
+        const { bytes, totalSize, identity } = await readVerifiedArtifactRange(target, sha256, range, this.#verifiedContent.get(verificationKey), signal);
+        this.#verifiedContent.set(verificationKey, identity);
+        return { bytes, mimeType: manifest.mimeType, name, totalSize };
+    }
+    uri(workspaceId, sha256, provenanceHash, name) {
+        return `hoi4-agent://workspace/${encodeURIComponent(workspaceId)}/artifact/${sha256}/${provenanceHash}/${encodeURIComponent(name)}`;
+    }
+    parseUri(workspace, uri) {
+        let parsed;
+        try {
+            parsed = new URL(uri);
+        }
+        catch {
+            throw new ServiceError('ARTIFACT_URI_INVALID', 'Invalid artifact URI');
+        }
+        if (parsed.protocol !== 'hoi4-agent:' ||
+            parsed.hostname !== 'workspace' ||
+            parsed.username !== '' ||
+            parsed.password !== '' ||
+            parsed.port !== '' ||
+            parsed.search !== '' ||
+            parsed.hash !== '')
+            throw new ServiceError('ARTIFACT_URI_INVALID', 'Invalid artifact URI');
+        let segments;
+        try {
+            segments = parsed.pathname.split('/').filter(Boolean).map(decodeURIComponent);
+        }
+        catch {
+            throw new ServiceError('ARTIFACT_URI_INVALID', 'Invalid artifact URI encoding');
+        }
+        if (segments.length !== 5 || segments[0] !== workspace.id || segments[1] !== 'artifact')
+            throw new ServiceError('ARTIFACT_WORKSPACE_MISMATCH', 'Artifact URI does not belong to this workspace');
+        const [, , sha256, provenanceHash, name] = segments;
+        if (!/^[a-f0-9]{64}$/u.test(sha256) ||
+            !/^[a-f0-9]{64}$/u.test(provenanceHash) ||
+            !isValidArtifactName(name))
+            throw new ServiceError('ARTIFACT_URI_INVALID', 'Invalid artifact URI components');
+        if (this.uri(workspace.id, sha256, provenanceHash, name) !== parsed.href) {
+            throw new ServiceError('ARTIFACT_URI_INVALID', 'Artifact URI is not canonical');
+        }
+        return { sha256: sha256, provenanceHash: provenanceHash, name: name };
+    }
+}
+//# sourceMappingURL=artifacts.js.map