@cueai/omni-reader-mcp 1.5.5 → 1.7.0

package/dist/operation-manager.js

@@ -4,8 +4,8 @@ import { OmniBridgeError } from "./errors.js";
 import { LEGACY_RECOVERY_FAILURE_CODE } from "./operation-journal.js";
 import { openAllowedFile, } from "./path-security.js";
 import { NOOP_PROGRESS } from "./progress.js";
-import { normalizeRepresentation } from "./protocol.js";
-import { localResultToResultField } from "./result-contract.js";
+import { normalizeRepresentation, } from "./protocol.js";
+import { LOCAL_ARTIFACT_RETENTION_WARNING, createFlatLocalResultCache, localResultToResultField, presentRetainedResult, } from "./result-contract.js";
 const TERMINAL_STATES = new Set([
     "COMPLETED",
     "FAILED",
@@ -36,6 +36,78 @@ function managerError(code, message, facts = {}) {
         retryable: facts.retryable ?? false,
     });
 }
+function journalIntegrityError(message, record) {
+    return managerError("JOURNAL_INTEGRITY_FAILED", message, record === undefined
+        ? {}
+        : {
+            operationCreated: record.operationId !== null,
+            fileUploaded: record.fileUploaded,
+            parserStarted: record.parserStarted,
+            billed: record.billed,
+            contentReleased: record.contentReleased,
+        });
+}
+function isBillingProfile(profile) {
+    return profile === "omni.direct_text_billing.v1"
+        || profile === "omni.direct_grounding_billing.v1";
+}
+function toJournalBilling(billing) {
+    return {
+        creditsCharged: billing.credits_charged,
+        creditsRemaining: billing.credits_remaining,
+    };
+}
+function toWireBilling(billing) {
+    return {
+        credits_charged: billing.creditsCharged,
+        credits_remaining: billing.creditsRemaining,
+    };
+}
+function resultBilling(result) {
+    if (result.status === "completed"
+        || result.status === "cleanup_pending"
+        || result.status === "canceled"
+        || result.status === "expired") {
+        return result.billing ?? null;
+    }
+    return null;
+}
+function projectBilling(result, billing) {
+    if (billing === null
+        || (result.status !== "completed"
+            && result.status !== "cleanup_pending"
+            && result.status !== "canceled"
+            && result.status !== "expired")) {
+        return result;
+    }
+    return { ...result, billing };
+}
+function requireWireBillingForSettledProfile(profile, billed, billing) {
+    if (!isBillingProfile(profile))
+        return billing ?? undefined;
+    if (!billed && billing !== null) {
+        throw journalIntegrityError("An unbilled direct terminal carries billing facts.");
+    }
+    if (billed && billing === null) {
+        throw journalIntegrityError("New-profile settlement billing is missing.");
+    }
+    return billing ?? undefined;
+}
+function assertDirectTerminalSnapshot(profile, snapshot) {
+    if (!isBillingProfile(profile))
+        return;
+    if ((snapshot.directProfile ?? null) !== profile) {
+        throw journalIntegrityError("IIIS changed the selected direct profile.");
+    }
+    if (snapshot.status === "CANCELED"
+        || snapshot.status === "FAILED"
+        || snapshot.status === "UNSUPPORTED"
+        || snapshot.status === "SETTLEMENT_DENIED") {
+        if (snapshot.billed || snapshot.contentReleased || snapshot.billing !== null) {
+            throw journalIntegrityError("A canceled or failed direct-v5 operation is not strictly uncharged.");
+        }
+    }
+}
 function canonicalValue(value) {
     if (value === null || typeof value === "string" || typeof value === "boolean") {
         return value;
@@ -162,6 +234,7 @@ function resultFromRecord(record) {
             status: "expired",
             operation_id: record.operationId,
             requires_user_confirmation: true,
+            ...(record.billing === null ? {} : { billing: toWireBilling(record.billing) }),
         };
     }
     if (record.state === "CANCELED") {
@@ -170,6 +243,7 @@ function resultFromRecord(record) {
             status: "canceled",
             operation_id: record.operationId,
             ...(cleanupDeadline === null ? {} : { cleanup_deadline: cleanupDeadline }),
+            ...(record.billing === null ? {} : { billing: toWireBilling(record.billing) }),
             data_handling: recordDataHandling(record),
         };
     }
@@ -188,6 +262,7 @@ function resultFromRecord(record) {
         return {
             status: "cleanup_pending",
             operation_id: record.operationId,
+            ...(record.billing === null ? {} : { billing: toWireBilling(record.billing) }),
             cleanup_deadline: record.resultExpiresAt ?? record.expiresAt ?? new Date(0).toISOString(),
             data_handling: recordDataHandling(record),
         };
@@ -217,30 +292,52 @@ function resultFromRecord(record) {
 export class OperationManager {
     #journal;
     #driver;
+    #presentResult;
     #now;
     #sleep;
     #submissions = new Map();
+    #submissionDelivery = new Map();
     #executions = new Map();
     #results = new Map();
     constructor(options) {
         this.#journal = options.journal;
         this.#driver = options.driver;
+        this.#presentResult = options.presentResult ?? (async (_record, result) => result);
         this.#now = options.now ?? Date.now;
         this.#sleep = options.sleep ?? defaultSleep;
     }
+    async #strengthenResultDelivery(record, requested) {
+        if (requested === "auto" || record.resultDeliveryEffective === "artifact") {
+            return record;
+        }
+        if (record.requestIdentityHmac === null
+            && record.errorCode === LEGACY_RECOVERY_FAILURE_CODE) {
+            return record;
+        }
+        return this.#journal.strengthenResultDelivery(record.clientRequestId, requested);
+    }
     async submit(input) {
         const requestHash = operationRequestHash(input);
+        const requestedDelivery = input.resultDelivery ?? "auto";
+        if (requestedDelivery === "artifact"
+            || this.#submissionDelivery.get(requestHash) === undefined) {
+            this.#submissionDelivery.set(requestHash, requestedDelivery);
+        }
         const active = this.#submissions.get(requestHash);
-        if (active !== undefined)
-            return active;
+        if (active !== undefined) {
+            const record = await active;
+            return this.#strengthenResultDelivery(record, requestedDelivery);
+        }
         const pending = this.#submit(input);
         this.#submissions.set(requestHash, pending);
         try {
-            return await pending;
+            const record = await pending;
+            return await this.#strengthenResultDelivery(record, this.#submissionDelivery.get(requestHash) ?? requestedDelivery);
         }
         finally {
             if (this.#submissions.get(requestHash) === pending) {
                 this.#submissions.delete(requestHash);
+                this.#submissionDelivery.delete(requestHash);
             }
         }
     }
@@ -282,7 +379,7 @@ export class OperationManager {
                 effectiveInput = { ...input, clientRequestId: matching.clientRequestId };
             }
             else {
-                record = await this.#journal.beginIntent(input.clientRequestId, identityJson, input.sourceKind, sourceLocator, representation);
+                record = await this.#journal.beginIntent(input.clientRequestId, identityJson, input.sourceKind, sourceLocator, representation, input.resultDelivery ?? "auto");
             }
         }
         else if (record.requestIdentityHmac === null) {
@@ -291,18 +388,26 @@ export class OperationManager {
             // recovery failure. It can never be resumed as grounded/layout.
             const migrated = await this.#journal.migrateLegacyRecord(input.clientRequestId, identityJson, sourceLocator);
             record = migrated === null
-                ? await this.#journal.beginIntent(input.clientRequestId, identityJson, input.sourceKind, sourceLocator, representation)
+                ? await this.#journal.beginIntent(input.clientRequestId, identityJson, input.sourceKind, sourceLocator, representation, input.resultDelivery ?? "auto")
                 : migrated;
             if (TERMINAL_STATES.has(record.state))
                 return record;
         }
         else {
-            record = await this.#journal.beginIntent(input.clientRequestId, identityJson, input.sourceKind, sourceLocator, representation);
+            record = await this.#journal.beginIntent(input.clientRequestId, identityJson, input.sourceKind, sourceLocator, representation, input.resultDelivery ?? "auto");
         }
+        record = await this.#strengthenResultDelivery(record, input.resultDelivery ?? "auto");
         const signal = effectiveInput.signal ?? new AbortController().signal;
         if (TERMINAL_STATES.has(record.state))
             return record;
         if (record.state !== "CREATED") {
+            if (record.sourceKind === "url"
+                && record.operationId !== null) {
+                // The remote server already owns this operation. A repeated parse call
+                // would create or attach to a second remote submission; callers must
+                // reuse the journaled operation and continue through status instead.
+                return record;
+            }
             if (record.operationId !== null && this.#executions.has(record.operationId)) {
                 return record;
             }
@@ -334,6 +439,45 @@ export class OperationManager {
             throw structured;
         }
     }
+    async #bindResultBilling(record, result) {
+        const billing = resultBilling(result);
+        if (billing === null)
+            return record;
+        const latest = await this.#journal.loadByRequestId(record.clientRequestId) ?? record;
+        const directProfile = latest.sourceKind === "url" ? null : latest.directProfile;
+        if (latest.sourceKind === "local" && directProfile === null) {
+            throw journalIntegrityError("A local terminal carries billing without a saved direct profile.", latest);
+        }
+        return this.#journal.bindSettlementFacts(latest.clientRequestId, {
+            directProfile,
+            billing: toJournalBilling(billing),
+        });
+    }
+    async #normalizeResultBilling(record, result) {
+        const bound = await this.#bindResultBilling(record, result);
+        const billing = resultBilling(result)
+            ?? (bound.billing === null ? null : toWireBilling(bound.billing));
+        if (isBillingProfile(bound.directProfile)) {
+            if (result.status === "failed" || result.status === "canceled") {
+                if (bound.billed || bound.billing !== null || bound.contentReleased) {
+                    throw journalIntegrityError("A failed or canceled direct-v5 terminal is not strictly uncharged.", bound);
+                }
+            }
+            else if (result.status === "completed"
+                || (result.status === "cleanup_pending" && result.result !== undefined)) {
+                requireWireBillingForSettledProfile(bound.directProfile, bound.billed, billing);
+            }
+        }
+        return projectBilling(result, billing);
+    }
+    async #present(record, canonicalResult) {
+        if (canonicalResult.status === "processing")
+            return canonicalResult;
+        const latest = record.operationId === null
+            ? await this.#journal.loadByRequestId(record.clientRequestId)
+            : await this.#journal.loadByOperationId(record.operationId);
+        return this.#presentResult(latest ?? record, canonicalResult);
+    }
     async submitResult(input, foregroundBudgetMs = FOREGROUND_BUDGET_MS) {
         const startedAt = this.#now();
         let record = await this.submit(input);
@@ -341,19 +485,20 @@ export class OperationManager {
             ? undefined
             : this.#results.get(record.operationId);
         if (existingResult !== undefined)
-            return existingResult;
+            return this.#present(record, 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);
+            if (TERMINAL_STATES.has(record.state) && record.operationId !== null) {
+                return this.statusResult(record.operationId, 0, input.signal);
+            }
+            return this.#present(record, 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);
+            return this.#present(record, resultFromRecord(record));
         }
         const winner = await Promise.race([
             execution.settled.then((result) => ({ kind: "completed", result })),
@@ -361,76 +506,81 @@ export class OperationManager {
         ]);
         if (winner.kind === "completed") {
             return this.#now() - startedAt < foregroundBudgetMs
-                ? winner.result
-                : resultFromRecord(record);
+                ? this.#present(record, winner.result)
+                : this.#present(record, 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);
+        return this.#present(record, 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 (cached !== undefined && TERMINAL_STATES.has(record.state)) {
+            return this.#present(record, 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;
+                const normalized = await this.#normalizeResultBilling(record, recovered);
+                this.#results.set(operationId, normalized);
+                return this.#present(record, normalized);
             }
-            return resultFromRecord(record);
+            return this.#present(record, 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);
+            return this.#present(record, 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;
+                return this.#present(record, statusResult);
             }
             execution = this.#executions.get(operationId);
-            if (execution === undefined)
-                return statusResult ?? resultFromRecord(record);
+            if (execution === undefined) {
+                return this.#present(record, 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);
+        if (boundedWait === 0) {
+            return this.#present(record, 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;
+            return this.#present(record, 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);
+        return this.#present(record, this.#results.get(operationId) ?? resultFromRecord(record));
     }
     async cancelResult(operationId, signal = new AbortController().signal) {
+        let record = await this.#existingOperation(operationId);
         const existing = this.#results.get(operationId);
-        if (existing !== undefined && existing.status !== "processing")
-            return existing;
+        if (existing !== undefined && existing.status !== "processing") {
+            return this.#present(record, existing);
+        }
         const execution = this.#executions.get(operationId);
         if (execution !== undefined) {
             await execution.handle.cancel();
-            return execution.settled;
+            const settled = await execution.settled;
+            record = await this.#existingOperation(operationId);
+            return this.#present(record, settled);
         }
-        const record = await this.cancel(operationId, signal);
-        return this.#results.get(operationId) ?? resultFromRecord(record);
+        record = await this.cancel(operationId, signal);
+        return this.#present(record, this.#results.get(operationId) ?? resultFromRecord(record));
     }
     async status(operationId, waitMs, signal = new AbortController().signal) {
         const record = await this.#existingOperation(operationId);
@@ -448,7 +598,7 @@ export class OperationManager {
             return record;
         const updated = await this.#applyUpdate(record, update);
         if (update.result !== undefined && updated.operationId !== null) {
-            this.#results.set(updated.operationId, update.result);
+            this.#results.set(updated.operationId, await this.#normalizeResultBilling(updated, update.result));
         }
         return updated;
     }
@@ -462,7 +612,7 @@ export class OperationManager {
         if (!isExecution(start)) {
             const updated = await this.#applyUpdate(record, start);
             if (start.result !== undefined && updated.operationId !== null) {
-                this.#results.set(updated.operationId, start.result);
+                this.#results.set(updated.operationId, await this.#normalizeResultBilling(updated, start.result));
             }
             return updated;
         }
@@ -474,16 +624,17 @@ export class OperationManager {
         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);
+            const updated = current !== null && !TERMINAL_STATES.has(current.state)
+                ? await this.#applyUpdate(current, completion.update)
+                : current ?? initial;
+            const normalized = await this.#normalizeResultBilling(updated, completion.result);
+            if (normalized.status !== "processing") {
+                this.#results.set(operationId, normalized);
             }
             else {
                 this.#results.delete(operationId);
             }
-            return completion.result;
+            return normalized;
         }).catch(async (error) => {
             const structured = error instanceof OmniBridgeError
                 ? error
@@ -537,18 +688,10 @@ export class OperationManager {
     }
     #shouldReuseByRequestHash(record) {
         if (!TERMINAL_STATES.has(record.state)) {
-            // Local uploads may resume mid-flight (restart recovery). URL recovery
-            // is only valid BEFORE the remote operation exists (GRANT_PENDING — the
-            // retry reuses the same request identity and the server's idempotency
-            // key dedupes). Once a URL op is PROCESSING (operationId set), the
-            // server owns it and a fresh parse creates a NEW operation id — reusing
-            // the stale record pairs old op_id with the server's new one →
-            // "changed the operation identifier" → REMOTE_PROTOCOL_ERROR
-            // (dogfood 2026-08-06). Reuse URL non-terminal records only when no
-            // operation id has been issued yet.
-            if (record.sourceKind === "url") {
-                return record.operationId === null;
-            }
+            // Local uploads may resume mid-flight. URL request identities must also
+            // reuse the existing record: before an operation id exists, the retry
+            // keeps the same server idempotency key; after it exists, #submit returns
+            // the record without calling parse again and callers continue by status.
             return true;
         }
         if (record.state !== "COMPLETED" || record.operationId === null)
@@ -585,7 +728,9 @@ export class OperationManager {
         return record;
     }
     async #applyUpdate(record, update) {
-        let current = record;
+        let current = update.result === undefined
+            ? record
+            : await this.#bindResultBilling(record, update.result);
         for (let attempt = 0; attempt < 4; attempt += 1) {
             try {
                 return await this.#journal.transition(current.clientRequestId, current.state, update.state, update.patch ?? {});
@@ -663,18 +808,34 @@ export async function hydrateInlineUrlResult(result, artifactStore) {
         ...start,
         resultDigest: `sha256:${createHash("sha256").update(bytes).digest("hex")}`,
     });
-    return { ...result, result: localResultToResultField(retention.result()) };
+    const local = retention.result();
+    return {
+        ...result,
+        result: localResultToResultField(local),
+        local_result_cache: createFlatLocalResultCache({
+            resultId: local.resultId,
+            resultBytes: local.resultBytes,
+            expiresAt: local.expiresAt,
+        }),
+    };
 }
 // hydrateInlineUrlResult is a pure local-storage optimization on top of content the caller
 // already has in full -- a local-disk failure here (e.g. disk full, permission error) must never
-// turn an otherwise-successful URL parse into a failure. This wrapper swallows any hydration
-// error and falls back to the original, un-hydrated result: the caller still gets their content;
-// they just lose local read_result/read_outline re-read capability for that particular result.
+// turn an otherwise-successful URL parse into a failure. Preserve the delivered inline content
+// and expose one exact warning instead of silently advertising unavailable local actions.
 export async function hydrateInlineUrlResultSafely(result, artifactStore) {
     try {
         return await hydrateInlineUrlResult(result, artifactStore);
     }
     catch {
+        if ((result.status === "completed" || result.status === "cleanup_pending")
+            && result.result?.kind === "inline") {
+            const { local_result_cache: _unavailableCache, ...delivered } = result;
+            return {
+                ...delivered,
+                delivery_warning: LOCAL_ARTIFACT_RETENTION_WARNING,
+            };
+        }
         return result;
     }
 }
@@ -723,6 +884,13 @@ function remoteFailure(result) {
         ...(error.constraints === undefined ? {} : { constraints: error.constraints }),
     });
 }
+function retainedFlatResultId(result) {
+    if (result.status !== "completed" && result.status !== "cleanup_pending") {
+        return undefined;
+    }
+    const cache = result.local_result_cache;
+    return cache !== undefined && "result_id" in cache ? cache.result_id : undefined;
+}
 function remoteResultUpdate(result, expectedOperationId) {
     if (result.status === "failed")
         throw remoteFailure(result);
@@ -770,6 +938,9 @@ function remoteResultUpdate(result, expectedOperationId) {
                 processingCopy: "deleted",
                 temporaryData: "deleted",
                 deliveryResult: "deleted_after_ack",
+                ...(retainedFlatResultId(result) === undefined
+                    ? {}
+                    : { resultId: retainedFlatResultId(result) }),
             },
             result,
         };
@@ -793,6 +964,9 @@ function remoteResultUpdate(result, expectedOperationId) {
                 temporaryData: result.data_handling.temporary_data,
                 deliveryResult: "pending",
                 resultExpiresAt: result.cleanup_deadline,
+                ...(retainedFlatResultId(result) === undefined
+                    ? {}
+                    : { resultId: retainedFlatResultId(result) }),
             },
             result,
         };
@@ -890,11 +1064,25 @@ function localResultValue(local) {
         next_cursor: local.nextCursor,
     };
 }
-function completedLocalParse(local) {
+function localResultCache(local) {
+    if (local.kind === "bundle") {
+        return {
+            expires_at: local.expiresAt,
+            discard_action: "discard_result",
+        };
+    }
+    return createFlatLocalResultCache({
+        resultId: local.resultId,
+        resultBytes: local.resultBytes,
+        expiresAt: local.expiresAt,
+    });
+}
+function completedLocalParse(local, billing) {
     return {
         status: "completed",
         operation_id: local.operationId,
         result: localResultValue(local),
+        ...(billing === undefined ? {} : { billing }),
         data_handling: {
             processing_copy: "deleted",
             temporary_data: "deleted",
@@ -902,19 +1090,15 @@ function completedLocalParse(local) {
             original_source: "unchanged",
             remote_content_retained: false,
         },
-        ...(local.kind === "artifact" || local.kind === "bundle" ? {
-            local_result_cache: {
-                expires_at: local.expiresAt,
-                discard_action: "discard_result",
-            },
-        } : {}),
+        local_result_cache: localResultCache(local),
     };
 }
-function cleanupPendingParse(local, cleanupDeadline) {
+function cleanupPendingParse(local, cleanupDeadline, billing) {
     return {
         status: "cleanup_pending",
         operation_id: local.operationId,
         result: localResultValue(local),
+        ...(billing === undefined ? {} : { billing }),
         cleanup_deadline: cleanupDeadline,
         data_handling: {
             processing_copy: "pending",
@@ -922,6 +1106,41 @@ function cleanupPendingParse(local, cleanupDeadline) {
             delivery_result: "pending",
             original_source: "unchanged",
         },
+        local_result_cache: localResultCache(local),
+    };
+}
+function withRecoveredRemoteResult(result, local) {
+    if (result.status !== "completed" && result.status !== "cleanup_pending") {
+        return result;
+    }
+    return {
+        ...result,
+        result: localResultValue(local),
+        local_result_cache: localResultCache(local),
+    };
+}
+function recoveredRemoteParse(record, local) {
+    if (record.operationId === null) {
+        throw managerError("OPERATION_ID_UNAVAILABLE", "The remote parse operation identifier is unavailable.");
+    }
+    if (record.state === "CLEANUP_PENDING") {
+        return {
+            status: "cleanup_pending",
+            operation_id: record.operationId,
+            result: localResultValue(local),
+            ...(record.billing === null ? {} : { billing: toWireBilling(record.billing) }),
+            cleanup_deadline: record.resultExpiresAt ?? record.expiresAt ?? new Date(0).toISOString(),
+            data_handling: recordDataHandling(record),
+            local_result_cache: localResultCache(local),
+        };
+    }
+    return {
+        status: "completed",
+        operation_id: record.operationId,
+        result: localResultValue(local),
+        ...(record.billing === null ? {} : { billing: toWireBilling(record.billing) }),
+        data_handling: recordDataHandling(record),
+        local_result_cache: localResultCache(local),
     };
 }
 function canceledParse(operationId, cleanupDeadline) {
@@ -972,7 +1191,9 @@ function safeOperationStage(status, fallback) {
         return "canceled";
     if (status === "EXPIRED" || status === "DELIVERY_EXPIRED")
         return "expired";
-    if (status === "FAILED" || status === "SETTLEMENT_DENIED")
+    if (status === "FAILED"
+        || status === "UNSUPPORTED"
+        || status === "SETTLEMENT_DENIED")
         return "failed";
     return safeJournalStage(fallback);
 }
@@ -1011,6 +1232,23 @@ function requireBundleResult(retention) {
     }
     return retention.bundleResult();
 }
+async function requireExpectedBundleDetail(local, expectedDetail, retention) {
+    if (local.kind === "bundle" && local.detail === expectedDetail)
+        return local;
+    try {
+        await retention.abort();
+    }
+    catch {
+        // Preserve the exact-detail protocol failure over best-effort local cleanup.
+    }
+    throw managerError("IIIS_INVALID_RESPONSE", "IIIS returned a result for a different representation detail.", {
+        operationCreated: true,
+        fileUploaded: true,
+        parserStarted: true,
+        billed: false,
+        contentReleased: false,
+    });
+}
 export function createLocalParseOperationManager(options) {
     const now = options.now ?? (() => new Date());
     const openFile = options.openFile ?? openAllowedFile;
@@ -1033,6 +1271,30 @@ export function createLocalParseOperationManager(options) {
         }
         throw managerError("JOURNAL_STATE_CONFLICT", "The operation changed repeatedly while saving a delivery checkpoint.", { operationCreated: true, retryable: true });
     }
+    async function recoverArtifactAccess(record, action) {
+        try {
+            return await action();
+        }
+        catch (error) {
+            const local = localFailure(error);
+            throw new OmniBridgeError({
+                code: local.code,
+                message: local.message,
+                failureScope: local.failureScope,
+                sourceKind: local.sourceKind,
+                userAction: local.userAction,
+                requestId: local.requestId,
+                operationCreated: local.operationCreated || record.operationId !== null,
+                fileUploaded: local.fileUploaded || record.fileUploaded,
+                parserStarted: local.parserStarted || record.parserStarted,
+                billed: local.billed || record.billed,
+                contentReleased: local.contentReleased || record.contentReleased,
+                retryable: local.retryable,
+                retryAfter: local.retryAfter,
+                constraints: local.constraints,
+            });
+        }
+    }
     // A retained logical bundle is reconstructed through its closed descriptor
     // and keeps the stored representation tuple; without the descriptor the
     // recovery fails safe instead of degrading the bundle to text.
@@ -1056,7 +1318,7 @@ export function createLocalParseOperationManager(options) {
                     contentReleased: record.contentReleased,
                 });
             }
-            const descriptor = await options.artifactStore.readBundleDescriptor(record.resultId);
+            const descriptor = await recoverArtifactAccess(record, () => options.artifactStore.readBundleDescriptor(record.resultId));
             if (descriptor === null || descriptor.kind !== "bundle") {
                 throw managerError("RESULT_NOT_AVAILABLE", "The retained local result bundle is unavailable.", {
                     operationCreated: true,
@@ -1068,11 +1330,11 @@ export function createLocalParseOperationManager(options) {
             }
             return descriptor;
         }
-        const preview = await options.artifactStore.read(record.resultId, undefined, 2_048);
+        const preview = await recoverArtifactAccess(record, () => 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);
+                : await recoverArtifactAccess(record, () => 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,
@@ -1101,6 +1363,16 @@ export function createLocalParseOperationManager(options) {
             ...(preview.nextCursor === undefined ? {} : { nextCursor: preview.nextCursor }),
         };
     }
+    async function preflightArtifactDelivery(input, recovery) {
+        const delivery = recovery?.resultDeliveryEffective ?? input.resultDelivery ?? "auto";
+        if (delivery !== "artifact")
+            return;
+        if (options.artifactStore.preflightWrite === undefined
+            || options.artifactStore.mintReadCursor === undefined) {
+            throw managerError("ARTIFACT_PREFLIGHT_FAILED", "The local result store cannot provide artifact delivery.");
+        }
+        await options.artifactStore.preflightWrite();
+    }
     async function startExecution(input, recovery) {
         // Recovery keeps the stored representation tuple exactly: status, download
         // (recoverLocalArtifact), and ACK all operate on the representation the
@@ -1136,6 +1408,7 @@ export function createLocalParseOperationManager(options) {
                 throw managerError("SOURCE_CHANGED_DURING_SUBMISSION", "The local source changed before the upload operation was created.", { retryable: true });
             }
             try {
+                await preflightArtifactDelivery(input, recovery);
                 // D2-D Task 14: the normalized detail reaches the grant boundary so
                 // CubeGrantClient selects the exact direct profile BEFORE constructing
                 // the v3 request and requires the v3 response tuple before any upload.
@@ -1147,6 +1420,9 @@ export function createLocalParseOperationManager(options) {
                     output: "markdown",
                     ...(representation.detail === "text" ? {} : { detail: representation.detail }),
                 }, input.clientRequestId, input.signal, { journal: false });
+                if (isBillingProfile(granted.directProfile)) {
+                    await options.journal.bindDirectProfile(input.clientRequestId, granted.directProfile);
+                }
             }
             catch (error) {
                 await opened.close().catch(() => undefined);
@@ -1208,9 +1484,17 @@ export function createLocalParseOperationManager(options) {
                 await (context?.progress ?? NOOP_PROGRESS).report(value, total, message, latestProgress ?? undefined);
             },
         };
+        const expectedDetail = granted?.requestedDetail ?? representation.detail;
+        if (expectedDetail !== representation.detail) {
+            await opened?.close().catch(() => undefined);
+            opened = undefined;
+            throw managerError("CUBE_PROTOCOL_ERROR", "Cube returned a grant for a different representation detail.", { operationCreated: true });
+        }
         const operation = {
             operationId,
             operationToken,
+            directProfile: granted?.directProfile ?? recovery?.directProfile ?? null,
+            expectedDetail,
             ...(granted === undefined || opened === undefined
                 ? {}
                 : {
@@ -1255,18 +1539,19 @@ export function createLocalParseOperationManager(options) {
                     recovery?.state === "ACK_PENDING" ||
                     recovery?.state === "CLEANUP_PENDING";
                 let local;
+                let released;
                 if (deliveryRecovery && recovery.resultId !== null) {
                     local = await recoverLocalArtifact(recovery);
                 }
                 else {
                     if (deliveryRecovery) {
-                        await options.iiisClient.downloadResult(operation, progress);
+                        released = await options.iiisClient.downloadResult(operation, progress);
                     }
                     else if (recovery?.state === "UPLOADING" || recovery?.state === "PROCESSING") {
-                        await options.iiisClient.recoverAndWait(operation);
+                        released = await options.iiisClient.recoverAndWait(operation);
                     }
                     else {
-                        await options.iiisClient.uploadAndWait(operation);
+                        released = await options.iiisClient.uploadAndWait(operation);
                     }
                     // Non-text results require the durable BundleLocalResult (both named
                     // parts verified and fsynced); ACK_PENDING is persisted only after
@@ -1275,6 +1560,27 @@ export function createLocalParseOperationManager(options) {
                         ? requireBundleResult(retention)
                         : retention.result();
                 }
+                if (representation.detail !== "text") {
+                    local = await requireExpectedBundleDetail(local, representation.detail, retention);
+                }
+                const directProfile = released?.directProfile
+                    ?? recovery?.directProfile
+                    ?? operation.directProfile
+                    ?? null;
+                if (released?.directProfile !== undefined
+                    && released.directProfile !== (operation.directProfile ?? null)) {
+                    throw journalIntegrityError("IIIS changed the selected direct profile.", recovery);
+                }
+                const recoveredBilling = recovery?.billing === null || recovery?.billing === undefined
+                    ? null
+                    : toWireBilling(recovery.billing);
+                const wireBilling = requireWireBillingForSettledProfile(directProfile, true, released?.billing ?? recoveredBilling);
+                if (wireBilling !== undefined) {
+                    await options.journal.bindSettlementFacts(input.clientRequestId, {
+                        directProfile,
+                        billing: toJournalBilling(wireBilling),
+                    });
+                }
                 const cleanupDeadline = recovery?.resultExpiresAt ?? new Date(now().getTime() + DELIVERY_TTL_SECONDS * 1000).toISOString();
                 const resultPatch = {
                     fileUploaded: true,
@@ -1325,7 +1631,7 @@ export function createLocalParseOperationManager(options) {
                             deliveryResult: "deleted_after_ack",
                         },
                     },
-                    result: completedLocalParse(local),
+                    result: completedLocalParse(local, wireBilling),
                 };
             }
             catch (error) {
@@ -1349,6 +1655,7 @@ export function createLocalParseOperationManager(options) {
                             result: processingParse(operationId, stage, latestPercent, confirmed.contentReleased === true),
                         };
                     }
+                    assertDirectTerminalSnapshot(operation.directProfile ?? null, inspected);
                     const patch = {
                         ...confirmed,
                         fileUploaded: confirmed.fileUploaded === true || inspected.fileUploaded,
@@ -1388,7 +1695,9 @@ export function createLocalParseOperationManager(options) {
                             },
                         };
                     }
-                    if (inspected.status === "FAILED" || inspected.status === "SETTLEMENT_DENIED") {
+                    if (inspected.status === "FAILED"
+                        || inspected.status === "UNSUPPORTED"
+                        || inspected.status === "SETTLEMENT_DENIED") {
                         const failed = managerError(inspected.status, `The Omni operation ended with status ${inspected.status}.`, {
                             operationCreated: true,
                             fileUploaded: patch.fileUploaded,
@@ -1444,12 +1753,14 @@ export function createLocalParseOperationManager(options) {
                         state: "FAILED",
                         patch: {
                             ...failurePatch(stable),
-                            // The ACK checkpoint may already have recorded a settled charge
-                            // (snapshot.patch at :1751 carries resultPatch's billed fact).
-                            // Never regress it — assertStableTransition blocks true->false —
-                            // the charge happened; this failure is about the local artifact,
-                            // not the settlement.
-                            billed: checkpointBilled || stable.billed,
+                            // Recovery starts from persisted monotonic facts. A protocol
+                            // rejection cannot make a confirmed upload, parser start,
+                            // settlement, or release become false merely because the invalid
+                            // response itself was not trusted.
+                            fileUploaded: recovery?.fileUploaded === true || stable.fileUploaded,
+                            parserStarted: recovery?.parserStarted === true || stable.parserStarted,
+                            billed: checkpointBilled || recovery?.billed === true || stable.billed,
+                            contentReleased: recovery?.contentReleased === true || stable.contentReleased,
                         },
                     },
                     result: {
@@ -1492,6 +1803,7 @@ export function createLocalParseOperationManager(options) {
             assertSameRepresentation(input, recovery);
         }
         const context = remoteContext(input.context);
+        await preflightArtifactDelivery(input, recovery);
         const result = await options.remoteClient.parse(context.source, input.clientRequestId, input.signal ?? new AbortController().signal, representation.detail);
         const hydrated = await hydrateInlineUrlResultSafely(result, options.artifactStore);
         return remoteResultUpdate(hydrated, recovery?.operationId ?? undefined);
@@ -1507,9 +1819,30 @@ export function createLocalParseOperationManager(options) {
             if (record.operationId === null)
                 return undefined;
             if (record.sourceKind === "url") {
-                if (options.remoteClient === undefined)
-                    return undefined;
+                if (options.remoteClient === undefined) {
+                    if (record.resultId === null || record.state !== "CLEANUP_PENDING") {
+                        return undefined;
+                    }
+                    return {
+                        state: record.state,
+                        result: recoveredRemoteParse(record, await recoverLocalArtifact(record)),
+                    };
+                }
                 const result = await options.remoteClient.status(record.operationId, waitMs, signal);
+                if (record.resultId !== null && record.state === "CLEANUP_PENDING") {
+                    let local;
+                    try {
+                        local = await recoverLocalArtifact(record);
+                    }
+                    catch {
+                        // A missing or corrupt retained copy must not block authoritative
+                        // remote status recovery. Rehydrate the returned body when it is
+                        // available, preserving the existing safe warning behavior.
+                    }
+                    if (local !== undefined) {
+                        return remoteResultUpdate(withRecoveredRemoteResult(result, local), record.operationId);
+                    }
+                }
                 const hydrated = await hydrateInlineUrlResultSafely(result, options.artifactStore);
                 return remoteResultUpdate(hydrated, record.operationId);
             }
@@ -1540,6 +1873,8 @@ export function createLocalParseOperationManager(options) {
             const operation = {
                 operationId: record.operationId,
                 operationToken: record.operationToken,
+                directProfile: record.directProfile,
+                expectedDetail: record.detail,
                 retention: {
                     async reset() { },
                     async begin() { },
@@ -1552,6 +1887,7 @@ export function createLocalParseOperationManager(options) {
             const inspected = options.iiisClient.cancelOperation === undefined
                 ? await options.iiisClient.inspectOperation(operation)
                 : await options.iiisClient.cancelOperation(operation);
+            assertDirectTerminalSnapshot(operation.directProfile ?? null, inspected);
             const patch = {
                 fileUploaded: inspected.fileUploaded,
                 parserStarted: inspected.parserStarted,
@@ -1585,7 +1921,9 @@ export function createLocalParseOperationManager(options) {
                     },
                 };
             }
-            if (inspected.status === "FAILED" || inspected.status === "SETTLEMENT_DENIED") {
+            if (inspected.status === "FAILED"
+                || inspected.status === "UNSUPPORTED"
+                || inspected.status === "SETTLEMENT_DENIED") {
                 return {
                     state: "FAILED",
                     patch: { ...patch, errorCode: inspected.status },
@@ -1611,7 +1949,16 @@ export function createLocalParseOperationManager(options) {
             if (record.operationId === null || record.state !== "COMPLETED")
                 return undefined;
             if (record.sourceKind === "local" && record.resultId !== null) {
-                return completedLocalParse(await recoverLocalArtifact(record));
+                return completedLocalParse(await recoverLocalArtifact(record), record.billing === null ? undefined : toWireBilling(record.billing));
+            }
+            if (record.sourceKind === "url" && record.resultId !== null) {
+                try {
+                    return recoveredRemoteParse(record, await recoverLocalArtifact(record));
+                }
+                catch (error) {
+                    if (options.remoteClient === undefined)
+                        throw error;
+                }
             }
             if (record.sourceKind === "url" && options.remoteClient !== undefined) {
                 const result = await options.remoteClient.status(record.operationId, 0, signal);
@@ -1624,6 +1971,18 @@ export function createLocalParseOperationManager(options) {
     return new OperationManager({
         journal: options.journal,
         driver,
+        presentResult: (record, canonicalResult) => presentRetainedResult(canonicalResult, record.resultDeliveryEffective, async (resultId, byteOffset) => {
+            if (options.artifactStore.mintReadCursor === undefined) {
+                throw managerError("LOCAL_RESULT_INTEGRITY_FAILED", "The retained result cursor capability is unavailable.", {
+                    operationCreated: record.operationId !== null,
+                    fileUploaded: record.fileUploaded,
+                    parserStarted: record.parserStarted,
+                    billed: record.billed,
+                    contentReleased: record.contentReleased,
+                });
+            }
+            return options.artifactStore.mintReadCursor(resultId, byteOffset);
+        }),
         now: () => now().getTime(),
         sleep: options.sleep,
     });