@cueai/omni-reader-mcp 1.0.2 → 1.1.0

package/dist/operation-manager.js

@@ -0,0 +1,1311 @@
+import { createHash } from "node:crypto";
+import { DELIVERY_TTL_SECONDS, FOREGROUND_BUDGET_MS, INLINE_RESULT_MAX_BYTES, STATUS_LONG_POLL_MAX_MS, STATUS_POLL_AFTER_SECONDS, } from "./constants.js";
+import { OmniBridgeError } from "./errors.js";
+import { openAllowedFile, } from "./path-security.js";
+import { NOOP_PROGRESS } from "./progress.js";
+const TERMINAL_STATES = new Set([
+    "COMPLETED",
+    "FAILED",
+    "CANCELED",
+    "EXPIRED",
+]);
+const STATE_ORDER = new Map([
+    ["CREATED", 0],
+    ["GRANT_PENDING", 1],
+    ["GRANT_ISSUED", 2],
+    ["UPLOADING", 3],
+    ["PROCESSING", 4],
+    ["RESULT_READY", 5],
+    ["ACK_PENDING", 6],
+    ["CLEANUP_PENDING", 7],
+    ["COMPLETED", 8],
+]);
+function managerError(code, message, facts = {}) {
+    return new OmniBridgeError({
+        code,
+        message,
+        failureScope: "operation",
+        operationCreated: facts.operationCreated ?? false,
+        fileUploaded: facts.fileUploaded ?? false,
+        parserStarted: facts.parserStarted ?? false,
+        billed: facts.billed ?? false,
+        contentReleased: facts.contentReleased ?? false,
+        retryable: facts.retryable ?? false,
+    });
+}
+function canonicalValue(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw managerError("INVALID_SOURCE_FACTS", "The operation source facts contain a non-finite number.");
+        }
+        return value;
+    }
+    if (Array.isArray(value))
+        return value.map(canonicalValue);
+    if (typeof value === "object") {
+        const object = value;
+        return Object.fromEntries(Object.keys(object).sort().map((key) => [key, canonicalValue(object[key])]));
+    }
+    throw managerError("INVALID_SOURCE_FACTS", "The operation source facts contain an unsupported value.");
+}
+export function operationRequestHash(input) {
+    const serialized = JSON.stringify({
+        source_kind: input.sourceKind,
+        source_facts: canonicalValue(input.sourceFacts),
+    });
+    return `sha256:${createHash("sha256").update(serialized, "utf8").digest("hex")}`;
+}
+function defaultSleep(milliseconds) {
+    return new Promise((resolve) => {
+        const timeout = setTimeout(resolve, milliseconds);
+        timeout.unref?.();
+    });
+}
+function safeToRetryCreation(error) {
+    return !error.operationCreated && !error.billed && error.retryable;
+}
+function safeToRecoverCreation(error) {
+    return error.operationCreated && !error.billed && error.retryable;
+}
+function failurePatch(error) {
+    return {
+        fileUploaded: error.fileUploaded,
+        parserStarted: error.parserStarted,
+        billed: error.billed,
+        contentReleased: error.contentReleased,
+        errorCode: error.code,
+    };
+}
+function isExecution(value) {
+    return "initial" in value && "completed" in value;
+}
+function recordDataHandling(record) {
+    const processingCopy = record.processingCopy === "deleted"
+        ? "deleted"
+        : record.processingCopy === "pending"
+            ? "pending"
+            : "in_use";
+    const temporaryData = record.temporaryData === "deleted"
+        ? "deleted"
+        : record.temporaryData === "pending"
+            ? "pending"
+            : "in_use";
+    const deliveryResult = record.deliveryResult === "deleted_after_ack"
+        ? "deleted_after_ack"
+        : record.deliveryResult === "pending"
+            ? "pending"
+            : record.contentReleased && record.resultExpiresAt !== null
+                ? { expires_at: record.resultExpiresAt }
+                : "not_created";
+    return {
+        processing_copy: processingCopy,
+        temporary_data: temporaryData,
+        delivery_result: deliveryResult,
+        original_source: "unchanged",
+    };
+}
+function resultFromRecord(record) {
+    if (record.operationId === null) {
+        const error = managerError("OPERATION_ID_UNAVAILABLE", "The parse operation has not received a recoverable operation identifier.", { retryable: true });
+        return { status: "failed", error: error.toJSON() };
+    }
+    if (record.state === "EXPIRED") {
+        return {
+            status: "expired",
+            operation_id: record.operationId,
+            requires_user_confirmation: true,
+        };
+    }
+    if (record.state === "CANCELED") {
+        const cleanupDeadline = record.resultExpiresAt ?? record.expiresAt;
+        return {
+            status: "canceled",
+            operation_id: record.operationId,
+            ...(cleanupDeadline === null ? {} : { cleanup_deadline: cleanupDeadline }),
+            data_handling: recordDataHandling(record),
+        };
+    }
+    if (record.state === "FAILED") {
+        const code = record.errorCode ?? "OPERATION_FAILED";
+        const error = managerError(code, `The Omni operation ended with status ${code}.`, {
+            operationCreated: true,
+            fileUploaded: record.fileUploaded,
+            parserStarted: record.parserStarted,
+            billed: record.billed,
+            contentReleased: record.contentReleased,
+        });
+        return { status: "failed", error: error.toJSON() };
+    }
+    if (record.state === "CLEANUP_PENDING") {
+        return {
+            status: "cleanup_pending",
+            operation_id: record.operationId,
+            cleanup_deadline: record.resultExpiresAt ?? record.expiresAt ?? new Date(0).toISOString(),
+            data_handling: recordDataHandling(record),
+        };
+    }
+    if (record.state === "COMPLETED") {
+        const error = managerError("RESULT_NOT_AVAILABLE", "The completed result is no longer available in this Bridge process.", {
+            operationCreated: true,
+            fileUploaded: record.fileUploaded,
+            parserStarted: record.parserStarted,
+            billed: record.billed,
+            contentReleased: record.contentReleased,
+        });
+        return { status: "failed", error: error.toJSON() };
+    }
+    return {
+        status: "processing",
+        operation_id: record.operationId,
+        stage: record.stage ?? record.state.toLowerCase(),
+        progress: record.progressPercent,
+        ...(record.progress === null ? {} : { progress_detail: record.progress }),
+        next_action: "check_status",
+        poll_after_seconds: STATUS_POLL_AFTER_SECONDS,
+        can_cancel: true,
+        data_handling: recordDataHandling(record),
+    };
+}
+export class OperationManager {
+    #journal;
+    #driver;
+    #now;
+    #sleep;
+    #submissions = new Map();
+    #executions = new Map();
+    #results = new Map();
+    constructor(options) {
+        this.#journal = options.journal;
+        this.#driver = options.driver;
+        this.#now = options.now ?? Date.now;
+        this.#sleep = options.sleep ?? defaultSleep;
+    }
+    async submit(input) {
+        const requestHash = operationRequestHash(input);
+        const active = this.#submissions.get(requestHash);
+        if (active !== undefined)
+            return active;
+        const pending = this.#submit(input, requestHash);
+        this.#submissions.set(requestHash, pending);
+        try {
+            return await pending;
+        }
+        finally {
+            if (this.#submissions.get(requestHash) === pending) {
+                this.#submissions.delete(requestHash);
+            }
+        }
+    }
+    async #submit(input, requestHash) {
+        let effectiveInput = input;
+        const sourceLocatorHash = typeof input.sourceFacts.sourceHash === "string"
+            ? input.sourceFacts.sourceHash
+            : null;
+        let record = await this.#journal.loadByRequestId(input.clientRequestId);
+        if (record === null) {
+            let matching = await this.#journal.loadLatestByRequestHash(requestHash);
+            if (matching === null &&
+                input.sourceKind === "local" &&
+                input.sourceFacts.sourceFingerprint === undefined &&
+                sourceLocatorHash !== null) {
+                matching = await this.#journal.loadLatestBySourceLocatorHash(sourceLocatorHash);
+            }
+            if (matching !== null && this.#shouldReuseByRequestHash(matching)) {
+                record = matching;
+                effectiveInput = { ...input, clientRequestId: matching.clientRequestId };
+            }
+            else {
+                record = await this.#journal.beginIntent(input.clientRequestId, requestHash, input.sourceKind, sourceLocatorHash);
+            }
+        }
+        else {
+            record = await this.#journal.beginIntent(input.clientRequestId, requestHash, input.sourceKind, sourceLocatorHash);
+        }
+        const signal = effectiveInput.signal ?? new AbortController().signal;
+        if (TERMINAL_STATES.has(record.state))
+            return record;
+        if (record.state !== "CREATED") {
+            if (record.operationId !== null && this.#executions.has(record.operationId)) {
+                return record;
+            }
+            return this.#resume(record, effectiveInput, signal);
+        }
+        try {
+            record = await this.#journal.transition(effectiveInput.clientRequestId, "CREATED", "GRANT_PENDING", {});
+        }
+        catch (error) {
+            if (!(error instanceof OmniBridgeError) || error.code !== "JOURNAL_STATE_CONFLICT") {
+                throw error;
+            }
+            const raced = await this.#journal.loadByRequestId(effectiveInput.clientRequestId);
+            if (raced === null)
+                throw error;
+            return TERMINAL_STATES.has(raced.state)
+                ? raced
+                : this.#resume(raced, effectiveInput, signal);
+        }
+        try {
+            const start = await this.#driver.create(effectiveInput, requestHash, signal);
+            return this.#acceptStart(record, start);
+        }
+        catch (error) {
+            const structured = error instanceof OmniBridgeError
+                ? error
+                : managerError("BRIDGE_INTERNAL_ERROR", "The local operation could not be created safely.", { operationCreated: true });
+            await this.#recordCreationFailure(effectiveInput.clientRequestId, structured);
+            throw structured;
+        }
+    }
+    async submitResult(input, foregroundBudgetMs = FOREGROUND_BUDGET_MS) {
+        const startedAt = this.#now();
+        let record = await this.submit(input);
+        const existingResult = record.operationId === null
+            ? undefined
+            : this.#results.get(record.operationId);
+        if (existingResult !== undefined)
+            return existingResult;
+        const execution = record.operationId === null
+            ? undefined
+            : this.#executions.get(record.operationId);
+        if (execution === undefined) {
+            return TERMINAL_STATES.has(record.state) && record.operationId !== null
+                ? this.statusResult(record.operationId, 0, input.signal)
+                : resultFromRecord(record);
+        }
+        const remaining = Math.max(0, foregroundBudgetMs - (this.#now() - startedAt));
+        if (remaining === 0) {
+            record = await this.#applyUpdate(record, execution.handle.snapshot());
+            return resultFromRecord(record);
+        }
+        const winner = await Promise.race([
+            execution.settled.then((result) => ({ kind: "completed", result })),
+            this.#sleep(remaining).then(() => ({ kind: "timeout" })),
+        ]);
+        if (winner.kind === "completed") {
+            return this.#now() - startedAt < foregroundBudgetMs
+                ? winner.result
+                : resultFromRecord(record);
+        }
+        const current = await this.#journal.loadByOperationId(record.operationId);
+        if (current !== null && !TERMINAL_STATES.has(current.state)) {
+            record = await this.#applyUpdate(current, execution.handle.snapshot());
+        }
+        else if (current !== null) {
+            record = current;
+        }
+        return resultFromRecord(record);
+    }
+    async statusResult(operationId, waitMs = 0, signal = new AbortController().signal) {
+        const boundedWait = Math.min(STATUS_LONG_POLL_MAX_MS, Math.max(0, waitMs));
+        let record = await this.#existingOperation(operationId);
+        const cached = this.#results.get(operationId);
+        if (cached !== undefined && TERMINAL_STATES.has(record.state))
+            return cached;
+        if (TERMINAL_STATES.has(record.state)) {
+            const recovered = await this.#driver.result?.(record, signal);
+            if (recovered !== undefined) {
+                this.#results.set(operationId, recovered);
+                return recovered;
+            }
+            return resultFromRecord(record);
+        }
+        if (record.resultExpiresAt !== null &&
+            Date.parse(record.resultExpiresAt) <= this.#now()) {
+            record = await this.#journal.transition(record.clientRequestId, record.state, "EXPIRED", { errorCode: "RESULT_EXPIRED" });
+            return resultFromRecord(record);
+        }
+        let execution = this.#executions.get(operationId);
+        if (execution === undefined) {
+            record = await this.status(operationId, boundedWait, signal);
+            const statusResult = this.#results.get(operationId);
+            if (statusResult !== undefined && TERMINAL_STATES.has(record.state)) {
+                return statusResult;
+            }
+            execution = this.#executions.get(operationId);
+            if (execution === undefined)
+                return statusResult ?? resultFromRecord(record);
+        }
+        if (!TERMINAL_STATES.has(record.state)) {
+            record = await this.#applyUpdate(record, execution.handle.snapshot());
+        }
+        if (boundedWait === 0)
+            return this.#results.get(operationId) ?? resultFromRecord(record);
+        const winner = await Promise.race([
+            execution.settled.then((value) => ({ kind: "completed", value })),
+            this.#sleep(boundedWait).then(() => ({ kind: "timeout" })),
+        ]);
+        if (winner.kind === "completed")
+            return winner.value;
+        const current = await this.#existingOperation(operationId);
+        record = TERMINAL_STATES.has(current.state)
+            ? current
+            : await this.#applyUpdate(current, execution.handle.snapshot());
+        return this.#results.get(operationId) ?? resultFromRecord(record);
+    }
+    async cancelResult(operationId, signal = new AbortController().signal) {
+        const existing = this.#results.get(operationId);
+        if (existing !== undefined && existing.status !== "processing")
+            return existing;
+        const execution = this.#executions.get(operationId);
+        if (execution !== undefined) {
+            await execution.handle.cancel();
+            return execution.settled;
+        }
+        const record = await this.cancel(operationId, signal);
+        return this.#results.get(operationId) ?? resultFromRecord(record);
+    }
+    async status(operationId, waitMs, signal = new AbortController().signal) {
+        const record = await this.#existingOperation(operationId);
+        if (TERMINAL_STATES.has(record.state) || this.#driver.status === undefined)
+            return record;
+        const start = await this.#driver.status(record, waitMs, signal);
+        return start === undefined ? record : this.#acceptStart(record, start);
+    }
+    async cancel(operationId, signal = new AbortController().signal) {
+        const record = await this.#existingOperation(operationId);
+        if (TERMINAL_STATES.has(record.state) || this.#driver.cancel === undefined)
+            return record;
+        const update = await this.#driver.cancel(record, signal);
+        if (update === undefined)
+            return record;
+        const updated = await this.#applyUpdate(record, update);
+        if (update.result !== undefined && updated.operationId !== null) {
+            this.#results.set(updated.operationId, update.result);
+        }
+        return updated;
+    }
+    async #resume(record, input, signal) {
+        if (this.#driver.resume === undefined)
+            return record;
+        const start = await this.#driver.resume(record, input, signal);
+        return start === undefined ? record : this.#acceptStart(record, start);
+    }
+    async #acceptStart(record, start) {
+        if (!isExecution(start)) {
+            const updated = await this.#applyUpdate(record, start);
+            if (start.result !== undefined && updated.operationId !== null) {
+                this.#results.set(updated.operationId, start.result);
+            }
+            return updated;
+        }
+        const initial = await this.#applyUpdate(record, start.initial);
+        if (initial.operationId === null) {
+            throw managerError("OPERATION_ID_UNAVAILABLE", "The operation driver did not provide a recoverable operation identifier.", { retryable: true });
+        }
+        const operationId = initial.operationId;
+        let managed;
+        const settled = start.completed.then(async (completion) => {
+            const current = await this.#journal.loadByOperationId(operationId);
+            if (current !== null && !TERMINAL_STATES.has(current.state)) {
+                await this.#applyUpdate(current, completion.update);
+            }
+            if (completion.result.status !== "processing") {
+                this.#results.set(operationId, completion.result);
+            }
+            else {
+                this.#results.delete(operationId);
+            }
+            return completion.result;
+        }).catch(async (error) => {
+            const structured = error instanceof OmniBridgeError
+                ? error
+                : managerError("BRIDGE_INTERNAL_ERROR", "The local operation stopped unexpectedly.", { operationCreated: true });
+            const current = await this.#journal.loadByOperationId(operationId);
+            const updated = current !== null && !TERMINAL_STATES.has(current.state)
+                ? await this.#applyUpdate(current, {
+                    state: "FAILED",
+                    patch: failurePatch(structured),
+                })
+                : current;
+            const failed = { status: "failed", error: structured.toJSON() };
+            if (updated !== null && TERMINAL_STATES.has(updated.state)) {
+                this.#results.set(operationId, failed);
+            }
+            return failed;
+        }).finally(() => {
+            if (this.#executions.get(operationId) === managed) {
+                this.#executions.delete(operationId);
+            }
+        });
+        managed = { handle: start, settled };
+        this.#executions.set(operationId, managed);
+        return initial;
+    }
+    async #recordCreationFailure(clientRequestId, error) {
+        const current = await this.#journal.loadByRequestId(clientRequestId);
+        if (current === null || TERMINAL_STATES.has(current.state))
+            return;
+        try {
+            if (safeToRetryCreation(error) && current.state === "GRANT_PENDING") {
+                await this.#journal.transition(clientRequestId, current.state, "CREATED", { errorCode: null });
+                return;
+            }
+            if (safeToRecoverCreation(error) && current.state === "GRANT_PENDING") {
+                await this.#journal.transition(clientRequestId, current.state, current.state, failurePatch(error));
+                return;
+            }
+            if (current.state === "GRANT_PENDING" || current.operationId === null) {
+                await this.#journal.transition(clientRequestId, current.state, "FAILED", failurePatch(error));
+                return;
+            }
+            await this.#journal.transition(clientRequestId, current.state, current.state, failurePatch(error));
+        }
+        catch (journalError) {
+            if (!(journalError instanceof OmniBridgeError) ||
+                journalError.code !== "JOURNAL_STATE_CONFLICT") {
+                throw journalError;
+            }
+        }
+    }
+    #shouldReuseByRequestHash(record) {
+        if (!TERMINAL_STATES.has(record.state))
+            return true;
+        if (record.state !== "COMPLETED" || record.operationId === null)
+            return false;
+        if (this.#results.has(record.operationId))
+            return true;
+        const updatedAt = Date.parse(record.updatedAt);
+        return Number.isFinite(updatedAt) &&
+            updatedAt + DELIVERY_TTL_SECONDS * 1000 > this.#now();
+    }
+    async #existingOperation(operationId) {
+        const record = await this.#journal.loadByOperationId(operationId);
+        if (record === null) {
+            throw managerError("OPERATION_NOT_FOUND", "The requested parse operation is not available.");
+        }
+        return record;
+    }
+    async #applyUpdate(record, update) {
+        let current = record;
+        for (let attempt = 0; attempt < 4; attempt += 1) {
+            try {
+                return await this.#journal.transition(current.clientRequestId, current.state, update.state, update.patch ?? {});
+            }
+            catch (error) {
+                if (!(error instanceof OmniBridgeError) || error.code !== "JOURNAL_STATE_CONFLICT") {
+                    throw error;
+                }
+                const latest = await this.#journal.loadByRequestId(current.clientRequestId);
+                if (latest === null)
+                    throw error;
+                if (TERMINAL_STATES.has(latest.state))
+                    return latest;
+                const latestOrder = STATE_ORDER.get(latest.state);
+                const targetOrder = STATE_ORDER.get(update.state);
+                if (latest.state !== update.state &&
+                    !(targetOrder !== undefined && latestOrder !== undefined && latestOrder < targetOrder) &&
+                    !TERMINAL_STATES.has(update.state)) {
+                    return latest;
+                }
+                current = latest;
+            }
+        }
+        throw managerError("JOURNAL_STATE_CONFLICT", "The operation changed repeatedly while applying an update.", { operationCreated: record.operationId !== null, retryable: true });
+    }
+}
+function localContext(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw managerError("LOCAL_CONTEXT_INVALID", "The local parse context is unavailable.");
+    }
+    const context = value;
+    if (typeof context.source !== "string" ||
+        context.progress === undefined ||
+        typeof context.progress.report !== "function") {
+        throw managerError("LOCAL_CONTEXT_INVALID", "The local parse context is unavailable.");
+    }
+    return context;
+}
+function remoteContext(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw managerError("REMOTE_CONTEXT_INVALID", "The remote parse context is unavailable.");
+    }
+    const context = value;
+    if (typeof context.source !== "string") {
+        throw managerError("REMOTE_CONTEXT_INVALID", "The remote parse context is unavailable.");
+    }
+    return context;
+}
+function remoteFailure(result) {
+    const error = result.error;
+    return new OmniBridgeError({
+        code: error.code,
+        message: error.message,
+        ...(error.failure_scope === undefined ? {} : { failureScope: error.failure_scope }),
+        sourceKind: "url",
+        ...(error.user_action === undefined ? {} : { userAction: error.user_action }),
+        ...(error.request_id === undefined ? {} : { requestId: error.request_id }),
+        operationCreated: error.operation_created,
+        fileUploaded: error.file_uploaded,
+        parserStarted: error.parser_started,
+        billed: error.billed,
+        contentReleased: error.content_released,
+        retryable: error.retryable,
+        ...(error.retry_after === undefined ? {} : { retryAfter: error.retry_after }),
+        ...(error.constraints === undefined ? {} : { constraints: error.constraints }),
+    });
+}
+function remoteResultUpdate(result, expectedOperationId) {
+    if (result.status === "failed")
+        throw remoteFailure(result);
+    if (expectedOperationId !== undefined &&
+        result.operation_id !== expectedOperationId) {
+        throw managerError("REMOTE_PROTOCOL_ERROR", "The remote Omni response changed the operation identifier.", { operationCreated: true });
+    }
+    if (result.status === "processing") {
+        return {
+            state: "PROCESSING",
+            patch: {
+                operationId: result.operation_id,
+                errorCode: null,
+                stage: result.stage,
+                progressPercent: result.progress,
+                ...(result.progress_detail === undefined ? {} : { progress: result.progress_detail }),
+                processingCopy: result.data_handling.processing_copy,
+                temporaryData: result.data_handling.temporary_data,
+                deliveryResult: result.data_handling.delivery_result === "pending"
+                    ? "pending"
+                    : result.data_handling.delivery_result === "deleted_after_ack"
+                        ? "deleted_after_ack"
+                        : "not_created",
+                ...(typeof result.data_handling.delivery_result === "object"
+                    ? { resultExpiresAt: result.data_handling.delivery_result.expires_at }
+                    : {}),
+            },
+            result,
+        };
+    }
+    if (result.status === "completed") {
+        return {
+            state: "COMPLETED",
+            patch: {
+                operationId: result.operation_id,
+                errorCode: null,
+                parserStarted: true,
+                billed: true,
+                contentReleased: true,
+                stage: "completed",
+                progressPercent: 100,
+                processingCopy: "deleted",
+                temporaryData: "deleted",
+                deliveryResult: "deleted_after_ack",
+            },
+            result,
+        };
+    }
+    if (result.status === "cleanup_pending") {
+        return {
+            state: "CLEANUP_PENDING",
+            patch: {
+                operationId: result.operation_id,
+                errorCode: null,
+                parserStarted: true,
+                billed: true,
+                contentReleased: result.result !== undefined,
+                stage: "cleanup_pending",
+                progressPercent: result.result === undefined ? 99 : 100,
+                processingCopy: result.data_handling.processing_copy,
+                temporaryData: result.data_handling.temporary_data,
+                deliveryResult: "pending",
+                resultExpiresAt: result.cleanup_deadline,
+            },
+            result,
+        };
+    }
+    if (result.status === "canceled") {
+        return {
+            state: "CANCELED",
+            patch: {
+                operationId: result.operation_id,
+                errorCode: null,
+                stage: "canceled",
+                processingCopy: result.data_handling.processing_copy,
+                temporaryData: result.data_handling.temporary_data,
+                deliveryResult: result.data_handling.delivery_result === "pending"
+                    ? "pending"
+                    : result.data_handling.delivery_result === "deleted_after_ack"
+                        ? "deleted_after_ack"
+                        : "not_created",
+                ...(result.cleanup_deadline === undefined
+                    ? {}
+                    : { resultExpiresAt: result.cleanup_deadline }),
+            },
+            result,
+        };
+    }
+    return {
+        state: "EXPIRED",
+        patch: {
+            operationId: result.operation_id,
+            stage: "expired",
+            errorCode: "RESULT_EXPIRED",
+        },
+        result,
+    };
+}
+function localResultValue(local) {
+    if (local.kind === "inline")
+        return { kind: "inline", text: local.text };
+    if (local.nextCursor === undefined) {
+        throw managerError("LOCAL_RESULT_INTEGRITY_FAILED", "The local result artifact cursor is missing.", {
+            operationCreated: true,
+            fileUploaded: true,
+            parserStarted: true,
+            billed: true,
+            contentReleased: true,
+        });
+    }
+    return {
+        kind: "artifact",
+        result_id: local.resultId,
+        result_bytes: local.resultBytes,
+        expires_at: local.expiresAt,
+        preview: local.preview,
+        next_cursor: local.nextCursor,
+    };
+}
+function completedLocalParse(local) {
+    return {
+        status: "completed",
+        operation_id: local.operationId,
+        result: localResultValue(local),
+        data_handling: {
+            processing_copy: "deleted",
+            temporary_data: "deleted",
+            delivery_result: "deleted_after_ack",
+            original_source: "unchanged",
+            remote_content_retained: false,
+        },
+        ...(local.kind === "artifact" ? {
+            local_result_cache: {
+                expires_at: local.expiresAt,
+                discard_action: "discard_result",
+            },
+        } : {}),
+    };
+}
+function cleanupPendingParse(local, cleanupDeadline) {
+    return {
+        status: "cleanup_pending",
+        operation_id: local.operationId,
+        result: localResultValue(local),
+        cleanup_deadline: cleanupDeadline,
+        data_handling: {
+            processing_copy: "pending",
+            temporary_data: "pending",
+            delivery_result: "pending",
+            original_source: "unchanged",
+        },
+    };
+}
+function canceledParse(operationId, cleanupDeadline) {
+    return {
+        status: "canceled",
+        operation_id: operationId,
+        cleanup_deadline: cleanupDeadline,
+        data_handling: {
+            processing_copy: "pending",
+            temporary_data: "pending",
+            delivery_result: "not_created",
+            original_source: "unchanged",
+        },
+    };
+}
+function safeJournalStage(state) {
+    if (state === "UPLOADING")
+        return "uploading";
+    if (state === "PROCESSING")
+        return "parsing";
+    if (state === "RESULT_READY")
+        return "result_ready";
+    if (state === "ACK_PENDING")
+        return "ack_pending";
+    if (state === "CLEANUP_PENDING")
+        return "cleanup_pending";
+    if (state === "COMPLETED")
+        return "completed";
+    if (state === "FAILED")
+        return "failed";
+    if (state === "CANCELED")
+        return "canceled";
+    if (state === "EXPIRED")
+        return "expired";
+    return "preparing";
+}
+function safeOperationStage(status, fallback) {
+    if (status === "ISSUED" || status === "CLAIMED" || status === "UPLOADING") {
+        return "uploading";
+    }
+    if (status === "PROCESSING" || status === "SETTLING")
+        return "parsing";
+    if (status === "RELEASED")
+        return "result_ready";
+    if (status === "DELIVERED")
+        return "completed";
+    if (status === "CANCELED")
+        return "canceled";
+    if (status === "EXPIRED" || status === "DELIVERY_EXPIRED")
+        return "expired";
+    if (status === "FAILED" || status === "SETTLEMENT_DENIED")
+        return "failed";
+    return safeJournalStage(fallback);
+}
+function processingParse(operationId, stage, progress, contentReleased) {
+    return {
+        status: "processing",
+        operation_id: operationId,
+        stage,
+        progress: Math.min(99, Math.max(0, progress)),
+        next_action: "check_status",
+        poll_after_seconds: STATUS_POLL_AFTER_SECONDS,
+        can_cancel: true,
+        data_handling: {
+            processing_copy: contentReleased ? "pending" : "in_use",
+            temporary_data: contentReleased ? "pending" : "in_use",
+            delivery_result: contentReleased ? "pending" : "not_created",
+            original_source: "unchanged",
+        },
+    };
+}
+function localFailure(error) {
+    return error instanceof OmniBridgeError
+        ? error
+        : managerError("BRIDGE_INTERNAL_ERROR", "The local Omni operation could not complete.", { operationCreated: true });
+}
+export function createLocalParseOperationManager(options) {
+    const now = options.now ?? (() => new Date());
+    const openFile = options.openFile ?? openAllowedFile;
+    async function persistCheckpoint(clientRequestId, update) {
+        for (let attempt = 0; attempt < 4; attempt += 1) {
+            const current = await options.journal.loadByRequestId(clientRequestId);
+            if (current === null) {
+                throw managerError("JOURNAL_RECORD_NOT_FOUND", "The local operation journal record is missing.", { operationCreated: true, retryable: true });
+            }
+            if (TERMINAL_STATES.has(current.state))
+                return current;
+            try {
+                return await options.journal.transition(clientRequestId, current.state, update.state, update.patch ?? {});
+            }
+            catch (error) {
+                if (!(error instanceof OmniBridgeError) || error.code !== "JOURNAL_STATE_CONFLICT") {
+                    throw error;
+                }
+            }
+        }
+        throw managerError("JOURNAL_STATE_CONFLICT", "The operation changed repeatedly while saving a delivery checkpoint.", { operationCreated: true, retryable: true });
+    }
+    async function recoverLocalArtifact(record) {
+        if (record.operationId === null || record.resultId === null) {
+            throw managerError("RESULT_NOT_AVAILABLE", "The retained local result artifact is unavailable.", {
+                operationCreated: record.operationId !== null,
+                fileUploaded: record.fileUploaded,
+                parserStarted: record.parserStarted,
+                billed: record.billed,
+                contentReleased: record.contentReleased,
+            });
+        }
+        const preview = await options.artifactStore.read(record.resultId, undefined, 2_048);
+        if (preview.resultBytes <= INLINE_RESULT_MAX_BYTES) {
+            const recovered = preview.nextCursor === undefined
+                ? preview
+                : await options.artifactStore.read(record.resultId, undefined, INLINE_RESULT_MAX_BYTES);
+            if (recovered.nextCursor !== undefined) {
+                throw managerError("LOCAL_RESULT_INTEGRITY_FAILED", "The retained inline result was not fully readable.", {
+                    operationCreated: true,
+                    fileUploaded: record.fileUploaded,
+                    parserStarted: record.parserStarted,
+                    billed: record.billed,
+                    contentReleased: record.contentReleased,
+                });
+            }
+            return {
+                kind: "inline",
+                operationId: record.operationId,
+                resultId: recovered.resultId,
+                resultBytes: recovered.resultBytes,
+                expiresAt: recovered.expiresAt,
+                text: recovered.text,
+            };
+        }
+        return {
+            kind: "artifact",
+            operationId: record.operationId,
+            resultId: preview.resultId,
+            resultBytes: preview.resultBytes,
+            expiresAt: preview.expiresAt,
+            preview: preview.text,
+            ...(preview.nextCursor === undefined ? {} : { nextCursor: preview.nextCursor }),
+        };
+    }
+    async function startExecution(input, recovery) {
+        const recoveryOrder = recovery === undefined ? undefined : STATE_ORDER.get(recovery.state);
+        const needsUploadContext = recovery === undefined ||
+            recoveryOrder === undefined ||
+            recoveryOrder <= STATE_ORDER.get("GRANT_ISSUED");
+        const context = needsUploadContext
+            ? localContext(input.context)
+            : input.context === undefined
+                ? undefined
+                : localContext(input.context);
+        let opened;
+        let granted;
+        if (needsUploadContext) {
+            opened = await openFile(context.source, {
+                workspace: options.workspace,
+                extraRoots: options.extraRoots,
+            });
+            const expectedFingerprint = input.sourceFacts.sourceFingerprint;
+            if (typeof expectedFingerprint === "string" &&
+                opened.sourceFingerprint !== expectedFingerprint) {
+                await opened.close().catch(() => undefined);
+                opened = undefined;
+                throw managerError("SOURCE_CHANGED_DURING_SUBMISSION", "The local source changed before the upload operation was created.", { retryable: true });
+            }
+            try {
+                granted = await options.cubeClient.createGrant({
+                    contentLength: opened.size,
+                    contentType: opened.contentType,
+                    fileExtension: opened.safeExtension,
+                    noStore: true,
+                    output: "markdown",
+                }, input.clientRequestId, input.signal, { journal: false });
+            }
+            catch (error) {
+                await opened.close().catch(() => undefined);
+                throw error;
+            }
+        }
+        const operationId = granted?.operationId ?? recovery?.operationId;
+        const operationToken = granted?.operationToken ?? recovery?.operationToken;
+        if (operationId === null || operationId === undefined || operationToken === null || operationToken === undefined) {
+            await opened?.close().catch(() => undefined);
+            throw managerError("OPERATION_ID_UNAVAILABLE", "The recoverable operation identity is unavailable.", { operationCreated: recovery?.operationId !== null, retryable: true });
+        }
+        const controller = new AbortController();
+        const retention = options.artifactStore.createRetention();
+        let latestProgress = recovery?.progress ?? null;
+        let latestPercent = recovery?.progressPercent ?? 0;
+        let snapshot = {
+            state: recovery !== undefined && STATE_ORDER.get(recovery.state) >= STATE_ORDER.get("PROCESSING")
+                ? recovery.state
+                : "UPLOADING",
+            patch: {
+                operationId,
+                operationToken,
+                errorCode: null,
+                ...(granted === undefined ? {} : { expiresAt: granted.expiresAt }),
+                stage: recovery?.stage ?? "uploading",
+                progressPercent: latestPercent,
+                ...(latestProgress === null ? {} : { progress: latestProgress }),
+            },
+        };
+        const progress = {
+            async report(value, total, message, detail) {
+                const percent = total <= 0 ? 0 : Math.min(100, Math.max(0, value * 100 / total));
+                latestPercent = Math.max(latestPercent, percent);
+                if (detail !== undefined) {
+                    latestProgress = latestProgress === null
+                        ? detail
+                        : latestProgress.unit !== detail.unit
+                            ? latestProgress
+                            : {
+                                unit: detail.unit,
+                                completed: Math.max(latestProgress.completed, detail.completed),
+                                total: Math.max(latestProgress.total, detail.total),
+                            };
+                }
+                const state = recovery !== undefined && STATE_ORDER.get(recovery.state) > STATE_ORDER.get("PROCESSING")
+                    ? recovery.state
+                    : latestPercent >= 40
+                        ? "PROCESSING"
+                        : "UPLOADING";
+                snapshot = {
+                    state,
+                    patch: {
+                        stage: state === "UPLOADING" ? "uploading" : "parsing",
+                        progressPercent: latestPercent,
+                        ...(latestProgress === null ? {} : { progress: latestProgress }),
+                    },
+                };
+                await (context?.progress ?? NOOP_PROGRESS).report(value, total, message, latestProgress ?? undefined);
+            },
+        };
+        const operation = {
+            operationId,
+            operationToken,
+            ...(granted === undefined || opened === undefined
+                ? {}
+                : {
+                    parseGrant: granted.parseGrant,
+                    uploadUrl: granted.uploadUrl,
+                    expiresAt: granted.expiresAt,
+                    openedFile: opened,
+                }),
+            retention,
+            progress,
+            signal: controller.signal,
+        };
+        let cancellationSnapshot;
+        let cancellationPromise;
+        const cancel = () => {
+            controller.abort();
+            if (cancellationPromise !== undefined)
+                return cancellationPromise;
+            cancellationPromise = (async () => {
+                if (options.iiisClient.cancelOperation === undefined)
+                    return;
+                try {
+                    cancellationSnapshot = await options.iiisClient.cancelOperation({
+                        ...operation,
+                        signal: undefined,
+                    });
+                }
+                catch {
+                    // Inspection below determines the factual state when cancellation is uncertain.
+                }
+            })();
+            return cancellationPromise;
+        };
+        const abort = () => { void cancel(); };
+        if (input.signal?.aborted)
+            abort();
+        else
+            input.signal?.addEventListener("abort", abort, { once: true });
+        const completed = (async () => {
+            try {
+                const deliveryRecovery = recovery?.state === "RESULT_READY" ||
+                    recovery?.state === "ACK_PENDING" ||
+                    recovery?.state === "CLEANUP_PENDING";
+                let local;
+                if (deliveryRecovery && recovery.resultId !== null) {
+                    local = await recoverLocalArtifact(recovery);
+                }
+                else {
+                    if (deliveryRecovery) {
+                        await options.iiisClient.downloadResult(operation, progress);
+                    }
+                    else if (recovery?.state === "UPLOADING" || recovery?.state === "PROCESSING") {
+                        await options.iiisClient.recoverAndWait(operation);
+                    }
+                    else {
+                        await options.iiisClient.uploadAndWait(operation);
+                    }
+                    local = retention.result();
+                }
+                const cleanupDeadline = recovery?.resultExpiresAt ?? new Date(now().getTime() + DELIVERY_TTL_SECONDS * 1000).toISOString();
+                const resultPatch = {
+                    fileUploaded: true,
+                    parserStarted: true,
+                    billed: true,
+                    contentReleased: true,
+                    stage: "result_ready",
+                    progressPercent: 100,
+                    resultId: local.resultId,
+                    resultExpiresAt: cleanupDeadline,
+                    deliveryResult: "pending",
+                };
+                snapshot = { state: "ACK_PENDING", patch: resultPatch };
+                const checkpoint = await persistCheckpoint(input.clientRequestId, snapshot);
+                if (checkpoint.state !== "ACK_PENDING") {
+                    throw managerError("OPERATION_ALREADY_TERMINAL", "The parse operation became terminal before result acknowledgement.", {
+                        operationCreated: true,
+                        fileUploaded: checkpoint.fileUploaded,
+                        parserStarted: checkpoint.parserStarted,
+                        billed: checkpoint.billed,
+                        contentReleased: checkpoint.contentReleased,
+                    });
+                }
+                try {
+                    await options.iiisClient.ack(operation);
+                }
+                catch {
+                    return {
+                        update: {
+                            state: "CLEANUP_PENDING",
+                            patch: {
+                                ...resultPatch,
+                                processingCopy: "pending",
+                                temporaryData: "pending",
+                                deliveryResult: "pending",
+                            },
+                        },
+                        result: cleanupPendingParse(local, cleanupDeadline),
+                    };
+                }
+                return {
+                    update: {
+                        state: "COMPLETED",
+                        patch: {
+                            ...resultPatch,
+                            processingCopy: "deleted",
+                            temporaryData: "deleted",
+                            deliveryResult: "deleted_after_ack",
+                        },
+                    },
+                    result: completedLocalParse(local),
+                };
+            }
+            catch (error) {
+                const stable = localFailure(error);
+                if (controller.signal.aborted || stable.code === "CANCELED") {
+                    const confirmed = failurePatch(stable);
+                    let inspected;
+                    try {
+                        await cancellationPromise;
+                        inspected = cancellationSnapshot ??
+                            await options.iiisClient.inspectOperation(operation);
+                    }
+                    catch {
+                        const state = snapshot.state;
+                        const stage = safeJournalStage(state);
+                        return {
+                            update: {
+                                state,
+                                patch: { ...confirmed, errorCode: null, stage },
+                            },
+                            result: processingParse(operationId, stage, latestPercent, confirmed.contentReleased === true),
+                        };
+                    }
+                    const patch = {
+                        ...confirmed,
+                        fileUploaded: confirmed.fileUploaded === true || inspected.fileUploaded,
+                        parserStarted: confirmed.parserStarted === true || inspected.parserStarted,
+                        billed: confirmed.billed === true || inspected.billed,
+                        contentReleased: confirmed.contentReleased === true || inspected.contentReleased,
+                        errorCode: null,
+                        ...(inspected.expiresAt === null ? {} : { expiresAt: inspected.expiresAt }),
+                    };
+                    if (inspected.status === "CANCELED") {
+                        const cleanupDeadline = inspected.expiresAt ?? new Date(now().getTime() + DELIVERY_TTL_SECONDS * 1000).toISOString();
+                        return {
+                            update: {
+                                state: "CANCELED",
+                                patch: {
+                                    ...patch,
+                                    stage: "canceled",
+                                    processingCopy: "pending",
+                                    temporaryData: "pending",
+                                    deliveryResult: "not_created",
+                                    resultExpiresAt: cleanupDeadline,
+                                },
+                            },
+                            result: canceledParse(operationId, cleanupDeadline),
+                        };
+                    }
+                    if (inspected.status === "EXPIRED" || inspected.status === "DELIVERY_EXPIRED") {
+                        return {
+                            update: {
+                                state: "EXPIRED",
+                                patch: { ...patch, stage: "expired", errorCode: "RESULT_EXPIRED" },
+                            },
+                            result: {
+                                status: "expired",
+                                operation_id: operationId,
+                                requires_user_confirmation: true,
+                            },
+                        };
+                    }
+                    if (inspected.status === "FAILED" || inspected.status === "SETTLEMENT_DENIED") {
+                        const failed = managerError(inspected.status, `The Omni operation ended with status ${inspected.status}.`, {
+                            operationCreated: true,
+                            fileUploaded: patch.fileUploaded,
+                            parserStarted: patch.parserStarted,
+                            billed: patch.billed,
+                            contentReleased: patch.contentReleased,
+                        });
+                        return {
+                            update: {
+                                state: "FAILED",
+                                patch: { ...patch, stage: "failed", errorCode: inspected.status },
+                            },
+                            result: { status: "failed", error: failed.toJSON() },
+                        };
+                    }
+                    if (inspected.status === "DELIVERED") {
+                        const unavailable = managerError("RESULT_NOT_AVAILABLE", "The delivered result is no longer available locally.", {
+                            operationCreated: true,
+                            fileUploaded: patch.fileUploaded,
+                            parserStarted: patch.parserStarted,
+                            billed: patch.billed,
+                            contentReleased: patch.contentReleased,
+                        });
+                        return {
+                            update: {
+                                state: "FAILED",
+                                patch: {
+                                    ...patch,
+                                    stage: "failed",
+                                    errorCode: unavailable.code,
+                                    processingCopy: "deleted",
+                                    temporaryData: "deleted",
+                                    deliveryResult: "deleted_after_ack",
+                                },
+                            },
+                            result: { status: "failed", error: unavailable.toJSON() },
+                        };
+                    }
+                    const state = inspected.status === "RELEASED"
+                        ? "RESULT_READY"
+                        : inspected.status === "PROCESSING" || inspected.status === "SETTLING"
+                            ? "PROCESSING"
+                            : snapshot.state;
+                    const stage = safeJournalStage(state);
+                    return {
+                        update: { state, patch: { ...patch, stage } },
+                        result: processingParse(operationId, stage, latestPercent, patch.contentReleased === true),
+                    };
+                }
+                return {
+                    update: {
+                        state: "FAILED",
+                        patch: failurePatch(stable),
+                    },
+                    result: { status: "failed", error: stable.toJSON() },
+                };
+            }
+            finally {
+                input.signal?.removeEventListener("abort", abort);
+                await opened?.close().catch(() => undefined);
+            }
+        })();
+        return {
+            initial: snapshot,
+            completed,
+            snapshot: () => snapshot,
+            cancel,
+        };
+    }
+    async function startRemote(input, recovery) {
+        if (options.remoteClient === undefined) {
+            throw managerError("REMOTE_PARSE_UNAVAILABLE", "Remote URL parsing is not available in this Bridge build.", { retryable: true });
+        }
+        const context = remoteContext(input.context);
+        const result = await options.remoteClient.parse(context.source, input.clientRequestId, input.signal ?? new AbortController().signal);
+        return remoteResultUpdate(result, recovery?.operationId ?? undefined);
+    }
+    const driver = {
+        create: (input) => input.sourceKind === "url"
+            ? startRemote(input)
+            : startExecution(input),
+        resume: (record, input) => input.sourceKind === "url"
+            ? startRemote(input, record)
+            : startExecution(input, record),
+        status: async (record, waitMs, signal) => {
+            if (record.operationId === null)
+                return undefined;
+            if (record.sourceKind === "url") {
+                if (options.remoteClient === undefined)
+                    return undefined;
+                return remoteResultUpdate(await options.remoteClient.status(record.operationId, waitMs, signal), record.operationId);
+            }
+            const order = STATE_ORDER.get(record.state);
+            if (order === undefined || order < STATE_ORDER.get("UPLOADING"))
+                return undefined;
+            return startExecution({
+                sourceKind: "local",
+                sourceFacts: {},
+                clientRequestId: record.clientRequestId,
+                signal,
+            }, record);
+        },
+        cancel: async (record, signal) => {
+            if (record.operationId === null)
+                return undefined;
+            if (record.sourceKind === "url") {
+                if (options.remoteClient === undefined)
+                    return undefined;
+                return remoteResultUpdate(await options.remoteClient.cancel(record.operationId, signal), record.operationId);
+            }
+            if (record.operationToken === null)
+                return undefined;
+            const operation = {
+                operationId: record.operationId,
+                operationToken: record.operationToken,
+                retention: {
+                    async reset() { },
+                    async begin() { },
+                    async write() { },
+                    async complete() { },
+                    async abort() { },
+                },
+                signal,
+            };
+            const inspected = options.iiisClient.cancelOperation === undefined
+                ? await options.iiisClient.inspectOperation(operation)
+                : await options.iiisClient.cancelOperation(operation);
+            const patch = {
+                fileUploaded: inspected.fileUploaded,
+                parserStarted: inspected.parserStarted,
+                billed: inspected.billed,
+                contentReleased: inspected.contentReleased,
+                stage: safeOperationStage(inspected.status, record.state),
+                ...(inspected.expiresAt === null ? {} : { expiresAt: inspected.expiresAt }),
+            };
+            if (inspected.status === "CANCELED") {
+                const cleanupDeadline = inspected.expiresAt ?? new Date(now().getTime() + DELIVERY_TTL_SECONDS * 1000).toISOString();
+                return {
+                    state: "CANCELED",
+                    patch: {
+                        ...patch,
+                        processingCopy: "pending",
+                        temporaryData: "pending",
+                        deliveryResult: "not_created",
+                        resultExpiresAt: cleanupDeadline,
+                    },
+                    result: canceledParse(record.operationId, cleanupDeadline),
+                };
+            }
+            if (inspected.status === "EXPIRED" || inspected.status === "DELIVERY_EXPIRED") {
+                return {
+                    state: "EXPIRED",
+                    patch: { ...patch, errorCode: "RESULT_EXPIRED" },
+                    result: {
+                        status: "expired",
+                        operation_id: record.operationId,
+                        requires_user_confirmation: true,
+                    },
+                };
+            }
+            if (inspected.status === "FAILED" || inspected.status === "SETTLEMENT_DENIED") {
+                return {
+                    state: "FAILED",
+                    patch: { ...patch, errorCode: inspected.status },
+                };
+            }
+            if (inspected.status === "DELIVERED") {
+                return {
+                    state: "COMPLETED",
+                    patch: {
+                        ...patch,
+                        processingCopy: "deleted",
+                        temporaryData: "deleted",
+                        deliveryResult: "deleted_after_ack",
+                    },
+                };
+            }
+            return {
+                state: inspected.status === "RELEASED" ? "RESULT_READY" : record.state,
+                patch,
+            };
+        },
+        result: async (record, signal) => {
+            if (record.operationId === null || record.state !== "COMPLETED")
+                return undefined;
+            if (record.sourceKind === "local" && record.resultId !== null) {
+                return completedLocalParse(await recoverLocalArtifact(record));
+            }
+            if (record.sourceKind === "url" && options.remoteClient !== undefined) {
+                return await options.remoteClient.status(record.operationId, 0, signal);
+            }
+            return undefined;
+        },
+    };
+    return new OperationManager({
+        journal: options.journal,
+        driver,
+        now: () => now().getTime(),
+        sleep: options.sleep,
+    });
+}