@cueai/omni-reader-mcp 1.0.0

package/dist/artifact-store.js

@@ -0,0 +1,720 @@
+import { createHash, randomBytes } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { chmod, link, lstat, mkdir, open, readdir, realpath, unlink, } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { ARTIFACT_TTL_MS, INLINE_RESULT_MAX_BYTES, RESULT_CHUNK_MAX_BYTES } from "./constants.js";
+import { CursorCodec } from "./cursor.js";
+import { OmniBridgeError } from "./errors.js";
+const PREVIEW_MAX_BYTES = 2048;
+const METADATA_VERSION = 1;
+const RESULT_ID_PATTERN = /^result_[A-Za-z0-9_-]{16,64}$/;
+const TEMP_NAME_PATTERN = /^\.tmp-[A-Za-z0-9_-]+$/;
+const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/;
+function artifactError(code, message, retryable = false) {
+    return new OmniBridgeError({
+        code,
+        message,
+        fileUploaded: true,
+        billed: true,
+        contentReleased: true,
+        retryable,
+    });
+}
+function cacheError(code, message) {
+    return new OmniBridgeError({
+        code,
+        message,
+        fileUploaded: false,
+        billed: false,
+        contentReleased: false,
+        retryable: false,
+    });
+}
+function errno(error, code) {
+    return error instanceof Error && error.code === code;
+}
+function containsPath(parent, child) {
+    const relative = path.relative(parent, child);
+    return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== "..");
+}
+async function removeIfPresent(filePath) {
+    try {
+        await unlink(filePath);
+        return true;
+    }
+    catch (error) {
+        if (errno(error, "ENOENT"))
+            return false;
+        throw error;
+    }
+}
+async function syncDirectory(directory) {
+    let handle;
+    try {
+        handle = await open(directory, "r");
+        await handle.sync();
+    }
+    catch (error) {
+        if (!errno(error, "EINVAL") && !errno(error, "ENOTSUP") && !errno(error, "EISDIR")) {
+            throw error;
+        }
+    }
+    finally {
+        await handle?.close();
+    }
+}
+async function openNoFollow(filePath) {
+    return open(filePath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+}
+async function readPrivateFile(filePath, missingCode, missingMessage) {
+    let handle;
+    try {
+        handle = await openNoFollow(filePath);
+    }
+    catch (error) {
+        if (errno(error, "ENOENT"))
+            throw artifactError(missingCode, missingMessage);
+        if (errno(error, "ELOOP") || errno(error, "EMLINK")) {
+            throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The local result path is unsafe.");
+        }
+        throw error;
+    }
+    try {
+        const details = await handle.stat();
+        if (!details.isFile()) {
+            throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The local result path is unsafe.");
+        }
+        return await handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function openArtifactForRead(filePath) {
+    try {
+        return await openNoFollow(filePath);
+    }
+    catch (error) {
+        if (errno(error, "ENOENT")) {
+            throw artifactError("RESULT_NOT_FOUND", "The local result artifact is unavailable.");
+        }
+        if (errno(error, "ELOOP") || errno(error, "EMLINK")) {
+            throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The local result artifact path is unsafe.");
+        }
+        throw error;
+    }
+}
+async function installPrivateBytes(directory, finalPath, bytes) {
+    const temporaryPath = path.join(directory, `.tmp-${randomBytes(18).toString("base64url")}`);
+    let handle;
+    try {
+        handle = await open(temporaryPath, "wx", 0o600);
+        await handle.writeFile(bytes);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        try {
+            await link(temporaryPath, finalPath);
+        }
+        catch (error) {
+            if (errno(error, "EEXIST"))
+                return false;
+            throw error;
+        }
+        await chmod(finalPath, 0o600);
+        await syncDirectory(directory);
+        return true;
+    }
+    finally {
+        await handle?.close();
+        await removeIfPresent(temporaryPath);
+    }
+}
+async function readCursorKey(keyPath) {
+    let handle;
+    try {
+        handle = await openNoFollow(keyPath);
+    }
+    catch (error) {
+        if (errno(error, "ENOENT"))
+            return undefined;
+        if (errno(error, "ELOOP") || errno(error, "EMLINK")) {
+            throw cacheError("ARTIFACT_CACHE_UNSAFE", "The local artifact cursor key path is unsafe.");
+        }
+        throw error;
+    }
+    try {
+        const details = await handle.stat();
+        if (!details.isFile() || details.size !== 32) {
+            throw cacheError("ARTIFACT_KEY_INVALID", "The local artifact cursor key is invalid.");
+        }
+        const key = await handle.readFile();
+        if (key.length !== 32) {
+            throw cacheError("ARTIFACT_KEY_INVALID", "The local artifact cursor key is invalid.");
+        }
+        await handle.chmod(0o600);
+        return key;
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function loadOrCreateKey(rootDirectory) {
+    const keyPath = path.join(rootDirectory, "cursor.key");
+    const existing = await readCursorKey(keyPath);
+    if (existing !== undefined)
+        return existing;
+    const generated = randomBytes(32);
+    if (await installPrivateBytes(rootDirectory, keyPath, generated))
+        return generated;
+    const winner = await readCursorKey(keyPath);
+    if (winner === undefined) {
+        throw cacheError("ARTIFACT_KEY_INVALID", "The local artifact cursor key is unavailable.");
+    }
+    return winner;
+}
+function decodeUtf8(bytes) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw artifactError("RESULT_ENCODING_INVALID", "The released result is not valid UTF-8.");
+    }
+}
+async function readUtf8Slice(handle, offset, maximumBytes, totalBytes) {
+    const requested = Math.min(maximumBytes, totalBytes - offset);
+    if (requested <= 0)
+        return { text: "", bytesRead: 0 };
+    const buffer = Buffer.alloc(requested);
+    let filled = 0;
+    while (filled < requested) {
+        const result = await handle.read(buffer, filled, requested - filled, offset + filled);
+        if (result.bytesRead === 0)
+            break;
+        filled += result.bytesRead;
+    }
+    if (filled !== requested) {
+        throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The local result artifact is incomplete.");
+    }
+    for (let end = filled; end >= 0; end -= 1) {
+        try {
+            const text = new TextDecoder("utf-8", { fatal: true }).decode(buffer.subarray(0, end));
+            return { text, bytesRead: end };
+        }
+        catch {
+            // Backtrack only at the requested byte boundary.
+        }
+    }
+    throw artifactError("RESULT_ENCODING_INVALID", "The local result artifact is not valid UTF-8.");
+}
+function parseMetadata(value, expectedResultId) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The local result metadata is invalid.");
+    }
+    const record = value;
+    if (Object.keys(record).sort().join(",") !== "artifactName,createdAt,expiresAt,mediaType,resultBytes,resultDigest,resultId,version"
+        || record.version !== METADATA_VERSION
+        || record.resultId !== expectedResultId
+        || typeof record.resultBytes !== "number"
+        || !Number.isSafeInteger(record.resultBytes)
+        || record.resultBytes <= INLINE_RESULT_MAX_BYTES
+        || typeof record.mediaType !== "string"
+        || record.mediaType.length === 0
+        || typeof record.resultDigest !== "string"
+        || !SHA256_PATTERN.test(record.resultDigest)
+        || record.artifactName !== `${expectedResultId}.data`
+        || typeof record.createdAt !== "string"
+        || !Number.isFinite(Date.parse(record.createdAt))
+        || typeof record.expiresAt !== "string"
+        || !Number.isFinite(Date.parse(record.expiresAt))) {
+        throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The local result metadata is invalid.");
+    }
+    return record;
+}
+export function defaultArtifactRoot(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const homeDirectory = options.homeDirectory ?? os.homedir();
+    const env = options.env ?? process.env;
+    if (platform === "darwin") {
+        return path.posix.join(homeDirectory, "Library", "Caches", "cue", "omni-reader-mcp");
+    }
+    if (platform === "win32") {
+        const localAppData = env.LOCALAPPDATA;
+        if (localAppData === undefined || localAppData.length === 0) {
+            return path.win32.join(homeDirectory, "AppData", "Local", "Cue", "omni-reader-mcp", "Cache");
+        }
+        return path.win32.join(localAppData, "Cue", "omni-reader-mcp", "Cache");
+    }
+    const xdgCacheHome = env.XDG_CACHE_HOME;
+    const cacheHome = xdgCacheHome !== undefined && path.posix.isAbsolute(xdgCacheHome)
+        ? xdgCacheHome
+        : path.posix.join(homeDirectory, ".cache");
+    return path.posix.join(cacheHome, "cue", "omni-reader-mcp");
+}
+export class ArtifactStore {
+    #rootDirectory;
+    #resultsDirectory;
+    #retentionMs;
+    #now;
+    #cursor;
+    #closed = false;
+    constructor(rootDirectory, retentionMs, now, cursor) {
+        this.#rootDirectory = rootDirectory;
+        this.#resultsDirectory = path.join(rootDirectory, "results");
+        this.#retentionMs = retentionMs;
+        this.#now = now;
+        this.#cursor = cursor;
+    }
+    static async open(options = {}) {
+        const rootDirectory = path.resolve(options.rootDirectory ?? defaultArtifactRoot());
+        const projectDirectory = path.resolve(options.projectDirectory ?? process.cwd());
+        const retentionMs = options.retentionMs ?? ARTIFACT_TTL_MS;
+        const now = options.now ?? (() => new Date());
+        if (!Number.isSafeInteger(retentionMs) || retentionMs <= 0) {
+            throw new Error("artifact retention must be a positive integer");
+        }
+        await mkdir(rootDirectory, { recursive: true, mode: 0o700 });
+        const rootDetails = await lstat(rootDirectory);
+        if (!rootDetails.isDirectory() || rootDetails.isSymbolicLink()) {
+            throw cacheError("ARTIFACT_CACHE_UNSAFE", "The local artifact cache path is unsafe.");
+        }
+        const canonicalRoot = await realpath(rootDirectory);
+        const canonicalProject = await realpath(projectDirectory);
+        if (containsPath(canonicalProject, canonicalRoot) || containsPath(canonicalRoot, canonicalProject)) {
+            throw cacheError("ARTIFACT_CACHE_UNSAFE", "The local artifact cache must be outside the project directory.");
+        }
+        await chmod(canonicalRoot, 0o700);
+        const resultsDirectory = path.join(canonicalRoot, "results");
+        await mkdir(resultsDirectory, { recursive: true, mode: 0o700 });
+        const resultsDetails = await lstat(resultsDirectory);
+        if (!resultsDetails.isDirectory() || resultsDetails.isSymbolicLink()) {
+            throw cacheError("ARTIFACT_CACHE_UNSAFE", "The local artifact results path is unsafe.");
+        }
+        const canonicalResults = await realpath(resultsDirectory);
+        if (canonicalResults !== resultsDirectory || !containsPath(canonicalRoot, canonicalResults)) {
+            throw cacheError("ARTIFACT_CACHE_UNSAFE", "The local artifact results path is unsafe.");
+        }
+        await chmod(canonicalResults, 0o700);
+        const key = await loadOrCreateKey(canonicalRoot);
+        const store = new ArtifactStore(canonicalRoot, retentionMs, now, new CursorCodec(key, { now }));
+        await store.cleanupExpired();
+        return store;
+    }
+    get rootDirectory() {
+        return this.#rootDirectory;
+    }
+    createRetention() {
+        this.#requireOpen();
+        return new LocalResultRetention(this);
+    }
+    async read(resultId, cursor, maxBytes = RESULT_CHUNK_MAX_BYTES) {
+        this.#requireOpen();
+        const metadata = await this.#loadMetadata(resultId);
+        if (Date.parse(metadata.expiresAt) <= this.#now().getTime()) {
+            await this.discard(resultId);
+            throw artifactError("RESULT_EXPIRED", "The local result artifact has expired.");
+        }
+        let offset = 0;
+        if (cursor !== undefined) {
+            const payload = this.#cursor.decode(cursor);
+            if (payload.resultId !== resultId || payload.expiresAt !== metadata.expiresAt) {
+                throw artifactError("RESULT_CURSOR_MISMATCH", "The result cursor does not match this artifact.");
+            }
+            offset = payload.offset;
+        }
+        if (offset > metadata.resultBytes) {
+            throw artifactError("INVALID_RESULT_CURSOR", "The result cursor offset is invalid.");
+        }
+        const normalizedMaxBytes = Number.isFinite(maxBytes)
+            ? Math.trunc(maxBytes)
+            : RESULT_CHUNK_MAX_BYTES;
+        const requested = Math.min(RESULT_CHUNK_MAX_BYTES, Math.max(1, normalizedMaxBytes));
+        const artifactPath = path.join(this.#resultsDirectory, metadata.artifactName);
+        const handle = await openArtifactForRead(artifactPath);
+        let chunk;
+        try {
+            const artifactStat = await handle.stat();
+            if (!artifactStat.isFile() || artifactStat.size !== metadata.resultBytes) {
+                throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The local result artifact is invalid.");
+            }
+            chunk = await readUtf8Slice(handle, offset, requested, metadata.resultBytes);
+        }
+        finally {
+            await handle.close();
+        }
+        if (chunk.bytesRead === 0 && offset < metadata.resultBytes) {
+            throw artifactError("RESULT_CHUNK_TOO_SMALL", "The requested result chunk cannot fit the next UTF-8 character.");
+        }
+        const nextOffset = offset + chunk.bytesRead;
+        return {
+            resultId,
+            resultBytes: metadata.resultBytes,
+            expiresAt: metadata.expiresAt,
+            text: chunk.text,
+            ...(nextOffset < metadata.resultBytes
+                ? { nextCursor: this.#cursor.encode({ resultId, offset: nextOffset, expiresAt: metadata.expiresAt }) }
+                : {}),
+        };
+    }
+    async discard(resultId) {
+        this.#requireOpen();
+        if (!RESULT_ID_PATTERN.test(resultId))
+            return false;
+        const metadataPath = path.join(this.#resultsDirectory, `${resultId}.json`);
+        const artifactPath = path.join(this.#resultsDirectory, `${resultId}.data`);
+        const removedMetadata = await removeIfPresent(metadataPath);
+        const removedArtifact = await removeIfPresent(artifactPath);
+        if (removedMetadata || removedArtifact)
+            await syncDirectory(this.#resultsDirectory);
+        return removedMetadata || removedArtifact;
+    }
+    async cleanupExpired() {
+        this.#requireOpen();
+        const entries = await readdir(this.#resultsDirectory, { withFileTypes: true });
+        const now = this.#now().getTime();
+        let removed = 0;
+        const liveArtifacts = new Set();
+        for (const entry of entries) {
+            if (!entry.isFile() || !entry.name.endsWith(".json"))
+                continue;
+            const resultId = entry.name.slice(0, -5);
+            if (!RESULT_ID_PATTERN.test(resultId))
+                continue;
+            try {
+                const metadata = await this.#loadMetadata(resultId, true);
+                if (Date.parse(metadata.expiresAt) <= now) {
+                    if (await this.discard(resultId))
+                        removed += 1;
+                }
+                else {
+                    liveArtifacts.add(metadata.artifactName);
+                }
+            }
+            catch {
+                if (await this.discard(resultId))
+                    removed += 1;
+            }
+        }
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            const entryPath = path.join(this.#resultsDirectory, entry.name);
+            if (TEMP_NAME_PATTERN.test(entry.name)) {
+                let details;
+                try {
+                    details = await lstat(entryPath);
+                }
+                catch (error) {
+                    if (errno(error, "ENOENT"))
+                        continue;
+                    throw error;
+                }
+                if (details.mtimeMs + this.#retentionMs <= now && await removeIfPresent(entryPath))
+                    removed += 1;
+            }
+            else if (entry.name.endsWith(".data") && !liveArtifacts.has(entry.name)) {
+                let details;
+                try {
+                    details = await lstat(entryPath);
+                }
+                catch (error) {
+                    if (errno(error, "ENOENT"))
+                        continue;
+                    throw error;
+                }
+                if (details.mtimeMs + this.#retentionMs <= now && await removeIfPresent(entryPath))
+                    removed += 1;
+            }
+        }
+        if (removed > 0)
+            await syncDirectory(this.#resultsDirectory);
+        return removed;
+    }
+    async close() {
+        if (this.#closed)
+            return;
+        await this.cleanupExpired();
+        this.#closed = true;
+    }
+    async _finalizeArtifact(temporaryPath, metadata) {
+        this.#requireOpen();
+        const now = this.#now();
+        const createdAt = now.toISOString();
+        const expiresAt = new Date(now.getTime() + this.#retentionMs).toISOString();
+        const artifactName = `${metadata.resultId}.data`;
+        const artifactPath = path.join(this.#resultsDirectory, artifactName);
+        const metadataPath = path.join(this.#resultsDirectory, `${metadata.resultId}.json`);
+        try {
+            if (!await this.#installTemporary(temporaryPath, artifactPath)) {
+                throw artifactError("LOCAL_ARTIFACT_FAILED", "The local result artifact could not be installed.");
+            }
+            const stored = {
+                version: METADATA_VERSION,
+                resultId: metadata.resultId,
+                resultBytes: metadata.resultBytes,
+                mediaType: metadata.mediaType,
+                resultDigest: metadata.resultDigest,
+                artifactName,
+                createdAt,
+                expiresAt,
+            };
+            const installed = await installPrivateBytes(this.#resultsDirectory, metadataPath, Buffer.from(JSON.stringify(stored), "utf8"));
+            if (!installed) {
+                throw artifactError("LOCAL_ARTIFACT_FAILED", "The local result metadata could not be installed.");
+            }
+            const previewHandle = await openArtifactForRead(artifactPath);
+            let previewChunk;
+            try {
+                const artifactStat = await previewHandle.stat();
+                if (!artifactStat.isFile() || artifactStat.size !== metadata.resultBytes) {
+                    throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The local result artifact is invalid.");
+                }
+                previewChunk = await readUtf8Slice(previewHandle, 0, PREVIEW_MAX_BYTES, metadata.resultBytes);
+            }
+            finally {
+                await previewHandle.close();
+            }
+            return {
+                kind: "artifact",
+                operationId: metadata.operationId,
+                resultId: metadata.resultId,
+                resultBytes: metadata.resultBytes,
+                mediaType: metadata.mediaType,
+                resultDigest: metadata.resultDigest,
+                source: metadata.source,
+                artifactPath,
+                expiresAt,
+                preview: previewChunk.text,
+                ...(previewChunk.bytesRead < metadata.resultBytes
+                    ? { nextCursor: this.#cursor.encode({ resultId: metadata.resultId, offset: previewChunk.bytesRead, expiresAt }) }
+                    : {}),
+            };
+        }
+        catch (error) {
+            await removeIfPresent(metadataPath);
+            await removeIfPresent(artifactPath);
+            await removeIfPresent(temporaryPath);
+            throw error;
+        }
+    }
+    async _newTemporaryArtifact() {
+        this.#requireOpen();
+        for (let attempt = 0; attempt < 8; attempt += 1) {
+            const resultId = `result_${randomBytes(18).toString("base64url")}`;
+            const temporaryPath = path.join(this.#resultsDirectory, `.tmp-${randomBytes(18).toString("base64url")}`);
+            try {
+                const handle = await open(temporaryPath, "wx", 0o600);
+                return { resultId, temporaryPath, handle };
+            }
+            catch (error) {
+                if (!errno(error, "EEXIST"))
+                    throw error;
+            }
+        }
+        throw artifactError("LOCAL_ARTIFACT_FAILED", "A private local result artifact could not be created.", true);
+    }
+    async #installTemporary(temporaryPath, artifactPath) {
+        try {
+            await link(temporaryPath, artifactPath);
+        }
+        catch (error) {
+            if (errno(error, "EEXIST"))
+                return false;
+            throw error;
+        }
+        await chmod(artifactPath, 0o600);
+        await removeIfPresent(temporaryPath);
+        await syncDirectory(this.#resultsDirectory);
+        return true;
+    }
+    async #loadMetadata(resultId, allowExpired = false) {
+        if (!RESULT_ID_PATTERN.test(resultId)) {
+            throw artifactError("RESULT_NOT_FOUND", "The local result artifact is unavailable.");
+        }
+        const metadataPath = path.join(this.#resultsDirectory, `${resultId}.json`);
+        let value;
+        try {
+            const bytes = await readPrivateFile(metadataPath, "RESULT_NOT_FOUND", "The local result artifact is unavailable.");
+            value = JSON.parse(bytes.toString("utf8"));
+        }
+        catch (error) {
+            if (error instanceof SyntaxError) {
+                throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The local result metadata is invalid.");
+            }
+            throw error;
+        }
+        const metadata = parseMetadata(value, resultId);
+        if (!allowExpired && Date.parse(metadata.expiresAt) <= this.#now().getTime()) {
+            await this.discard(resultId);
+            throw artifactError("RESULT_EXPIRED", "The local result artifact has expired.");
+        }
+        return metadata;
+    }
+    #requireOpen() {
+        if (this.#closed)
+            throw cacheError("ARTIFACT_STORE_CLOSED", "The local artifact store is closed.");
+    }
+}
+export class LocalResultRetention {
+    #store;
+    #start;
+    #hash;
+    #decoder;
+    #encodingInvalid = false;
+    #received = 0;
+    #inlineChunks = [];
+    #artifact;
+    #result;
+    constructor(store) {
+        this.#store = store;
+    }
+    async reset() {
+        await this.abort();
+        this.#start = undefined;
+        this.#result = undefined;
+    }
+    async begin(metadata) {
+        if (this.#start !== undefined || this.#result !== undefined) {
+            throw artifactError("LOCAL_RESULT_STATE_INVALID", "Local result retention has already started.");
+        }
+        if (!Number.isSafeInteger(metadata.resultBytes)
+            || metadata.resultBytes < 0
+            || metadata.operationId.length === 0
+            || metadata.mediaType.length === 0) {
+            throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The released result metadata is invalid.");
+        }
+        this.#start = metadata;
+        this.#hash = createHash("sha256");
+        this.#decoder = new TextDecoder("utf-8", { fatal: true });
+        this.#encodingInvalid = false;
+        this.#received = 0;
+        this.#inlineChunks = [];
+        if (metadata.resultBytes > INLINE_RESULT_MAX_BYTES) {
+            const temporary = await this.#store._newTemporaryArtifact();
+            this.#artifact = temporary;
+        }
+    }
+    async write(chunk) {
+        if (this.#start === undefined || this.#hash === undefined || this.#decoder === undefined) {
+            throw artifactError("LOCAL_RESULT_STATE_INVALID", "Local result retention has not started.");
+        }
+        if (chunk.byteLength === 0)
+            return;
+        if (this.#received + chunk.byteLength > this.#start.resultBytes) {
+            await this.abort();
+            throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The released result exceeded its declared length.");
+        }
+        this.#hash.update(chunk);
+        if (!this.#encodingInvalid) {
+            try {
+                this.#decoder.decode(chunk, { stream: true });
+            }
+            catch {
+                this.#encodingInvalid = true;
+            }
+        }
+        if (this.#artifact === undefined) {
+            this.#inlineChunks.push(Buffer.from(chunk));
+        }
+        else {
+            const handle = this.#artifact.handle;
+            if (handle === undefined) {
+                throw artifactError("LOCAL_RESULT_STATE_INVALID", "The local artifact is not writable.");
+            }
+            let written = 0;
+            while (written < chunk.byteLength) {
+                const result = await handle.write(chunk, written, chunk.byteLength - written, null);
+                if (result.bytesWritten === 0) {
+                    await this.abort();
+                    throw artifactError("LOCAL_ARTIFACT_FAILED", "The local result artifact write stalled.", true);
+                }
+                written += result.bytesWritten;
+            }
+        }
+        this.#received += chunk.byteLength;
+    }
+    async complete(metadata) {
+        const start = this.#start;
+        const hash = this.#hash;
+        const decoder = this.#decoder;
+        if (start === undefined || hash === undefined || decoder === undefined || this.#result !== undefined) {
+            throw artifactError("LOCAL_RESULT_STATE_INVALID", "Local result retention cannot be completed.");
+        }
+        try {
+            if (metadata.operationId !== start.operationId
+                || metadata.resultBytes !== start.resultBytes
+                || metadata.mediaType !== start.mediaType
+                || metadata.source !== start.source
+                || this.#received !== start.resultBytes
+                || !SHA256_PATTERN.test(metadata.resultDigest)) {
+                throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The retained result metadata did not match.");
+            }
+            if (!this.#encodingInvalid) {
+                try {
+                    decoder.decode();
+                }
+                catch {
+                    this.#encodingInvalid = true;
+                }
+            }
+            if (this.#encodingInvalid) {
+                throw artifactError("RESULT_ENCODING_INVALID", "The released result is not valid UTF-8.");
+            }
+            const computedDigest = `sha256:${hash.digest("hex")}`;
+            if (computedDigest !== metadata.resultDigest) {
+                throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The retained result digest did not match.");
+            }
+            if (this.#artifact === undefined) {
+                const bytes = Buffer.concat(this.#inlineChunks);
+                this.#result = {
+                    kind: "inline",
+                    ...metadata,
+                    text: decodeUtf8(bytes),
+                };
+            }
+            else {
+                const handle = this.#artifact.handle;
+                if (handle === undefined) {
+                    throw artifactError("LOCAL_RESULT_STATE_INVALID", "The local artifact is not writable.");
+                }
+                await handle.sync();
+                await handle.close();
+                this.#artifact.handle = undefined;
+                this.#result = await this.#store._finalizeArtifact(this.#artifact.temporaryPath, {
+                    ...metadata,
+                    resultId: this.#artifact.resultId,
+                });
+            }
+        }
+        catch (error) {
+            await this.abort();
+            throw error;
+        }
+    }
+    result() {
+        if (this.#result === undefined) {
+            throw artifactError("LOCAL_RESULT_NOT_DURABLE", "The local result has not been retained durably.");
+        }
+        return this.#result;
+    }
+    async abort() {
+        const artifact = this.#artifact;
+        if (artifact?.handle !== undefined) {
+            await artifact.handle.close();
+            artifact.handle = undefined;
+        }
+        if (artifact !== undefined) {
+            await removeIfPresent(artifact.temporaryPath);
+            if (this.#result?.kind === "artifact") {
+                await this.#store.discard(this.#result.resultId);
+            }
+        }
+        this.#artifact = undefined;
+        this.#inlineChunks = [];
+        this.#hash = undefined;
+        this.#decoder = undefined;
+        this.#received = 0;
+        this.#result = undefined;
+    }
+}