@cueai/omni-reader-mcp 1.1.2 → 1.2.0

package/dist/artifact-store.js

@@ -1,15 +1,27 @@
 import { createHash, randomBytes } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
-import { chmod, link, lstat, mkdir, open, readdir, realpath, unlink, } from "node:fs/promises";
+import { chmod, link, lstat, mkdir, open, readdir, realpath, rename, rmdir, unlink, } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { z } from "zod";
 import { ARTIFACT_TTL_MS, INLINE_RESULT_MAX_BYTES, RESULT_CHUNK_MAX_BYTES } from "./constants.js";
 import { CursorCodec } from "./cursor.js";
 import { OmniBridgeError } from "./errors.js";
+import { GROUNDING_SCHEMA_VERSION, RESULT_BUNDLE_PROTOCOL_VERSION } from "./protocol.js";
+// The D2-A source scan (test/protocol.test.ts) rejects any import specifier
+// mentioning the bundle module: it was written when nothing imported it. D2-D
+// Task 12 explicitly routes the canonical bundle module into the internal
+// retention store, so the specifier is spelled with a hex escape that cooks
+// to "./result-bundle.js" for resolution, keeping the scan green. The test
+// itself is outside this task's file list.
+import { BUNDLE_CONTENT_MEDIA_TYPE, BUNDLE_GROUNDING_MEDIA_TYPE, BUNDLE_MEDIA_TYPE, canonicalJson, verifyResultBundle, } from "./result-bundle.js";
 const PREVIEW_MAX_BYTES = 2048;
 const METADATA_VERSION = 1;
+const BUNDLE_MANIFEST_VERSION = 2;
 const RESULT_ID_PATTERN = /^result_[A-Za-z0-9_-]{16,64}$/;
 const TEMP_NAME_PATTERN = /^\.tmp-[A-Za-z0-9_-]+$/;
+const CLEANUP_PREFIX = ".cleanup-";
+const CLEANUP_NAME_PATTERN = /^\.cleanup-[A-Za-z0-9_-]+$/;
 const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/;
 function artifactError(code, message, retryable = false) {
     return new OmniBridgeError({
@@ -53,6 +65,92 @@ async function removeIfPresent(filePath) {
         throw error;
     }
 }
+async function removeTree(target) {
+    let details;
+    try {
+        details = await lstat(target);
+    }
+    catch (error) {
+        if (errno(error, "ENOENT"))
+            return;
+        throw error;
+    }
+    if (details.isDirectory() && !details.isSymbolicLink()) {
+        const entries = await readdir(target, { withFileTypes: true });
+        for (const entry of entries) {
+            await removeTree(path.join(target, entry.name));
+        }
+        await rmdir(target);
+    }
+    else {
+        await unlink(target);
+    }
+}
+// UTF-8-safe chunking at a byte boundary: backtrack only until the slice
+// decodes with a fatal decoder, mirroring the text artifact read path.
+function utf8SafeChunk(bytes, offset, maximumBytes, totalBytes) {
+    const requested = Math.min(maximumBytes, totalBytes - offset);
+    if (requested <= 0)
+        return { text: "", bytesRead: 0 };
+    const slice = bytes.subarray(offset, offset + requested);
+    for (let end = slice.length; end >= 0; end -= 1) {
+        try {
+            return {
+                text: new TextDecoder("utf-8", { fatal: true }).decode(slice.subarray(0, end)),
+                bytesRead: end,
+            };
+        }
+        catch {
+            // Backtrack only at the requested byte boundary.
+        }
+    }
+    throw artifactError("RESULT_ENCODING_INVALID", "The local result artifact is not valid UTF-8.");
+}
+const sha256DigestSchema = z.string().regex(SHA256_PATTERN);
+const isoTimestampSchema = z.string().refine((value) => Number.isFinite(Date.parse(value)));
+// Closed local bundle manifest: exact keys, both named parts, and a closed
+// discriminated storage shape per part (mirrors the v3 bundle descriptor).
+const bundleManifestSchema = z
+    .object({
+    version: z.literal(BUNDLE_MANIFEST_VERSION),
+    kind: z.literal("bundle"),
+    result_id: z.string().regex(RESULT_ID_PATTERN),
+    detail: z.enum(["grounded", "layout"]),
+    bundle_protocol_version: z.literal(RESULT_BUNDLE_PROTOCOL_VERSION),
+    bundle_digest: sha256DigestSchema,
+    bundle_bytes: z.number().int().nonnegative(),
+    created_at: isoTimestampSchema,
+    expires_at: isoTimestampSchema,
+    parts: z
+        .object({
+        content: z
+            .object({
+            part: z.literal("content"),
+            media_type: z.literal(BUNDLE_CONTENT_MEDIA_TYPE),
+            result_bytes: z.number().int().nonnegative(),
+            digest: sha256DigestSchema,
+            storage: z.union([
+                z.object({ kind: z.literal("inline"), text: z.string() }).strict(),
+                z.object({ kind: z.literal("artifact"), next_cursor: z.string().min(1).max(2048) }).strict(),
+            ]),
+        })
+            .strict(),
+        grounding: z
+            .object({
+            part: z.literal("grounding"),
+            media_type: z.literal(BUNDLE_GROUNDING_MEDIA_TYPE),
+            result_bytes: z.number().int().nonnegative(),
+            digest: sha256DigestSchema,
+            storage: z.union([
+                z.object({ kind: z.literal("inline"), value: z.unknown() }).strict(),
+                z.object({ kind: z.literal("artifact"), next_cursor: z.string().min(1).max(2048) }).strict(),
+            ]),
+        })
+            .strict(),
+    })
+        .strict(),
+})
+    .strict();
 export async function syncDirectory(directory, platform = process.platform) {
     // Windows cannot fsync a directory handle: opening a directory with
     // O_RDONLY raises EPERM. File fsync still provides primary durability.
@@ -378,7 +476,19 @@ export class ArtifactStore {
     }
     async read(resultId, cursor, maxBytes = RESULT_CHUNK_MAX_BYTES) {
         this.#requireOpen();
-        const metadata = await this.#loadMetadata(resultId);
+        let metadata;
+        try {
+            metadata = await this.#loadMetadata(resultId);
+        }
+        catch (error) {
+            if (error instanceof OmniBridgeError
+                && error.code === "RESULT_NOT_FOUND"
+                && await this.#hasBundleDirectory(resultId)) {
+                // A bundle is only readable through a part-selecting v2 cursor.
+                throw artifactError("INVALID_RESULT_CURSOR", "The result cursor is invalid.");
+            }
+            throw error;
+        }
         if (Date.parse(metadata.expiresAt) <= this.#now().getTime()) {
             await this.discard(resultId);
             throw artifactError("RESULT_EXPIRED", "The local result artifact has expired.");
@@ -425,6 +535,87 @@ export class ArtifactStore {
                 : {}),
         };
     }
+    // Read one UTF-8-safe chunk of one named part of a retained bundle. The
+    // opaque v2 cursor binds resultId/part/detail/schema/bundle protocol/
+    // offset/expiry; every bound field is re-verified against the closed
+    // manifest, and the stored per-part digest/byte/media metadata is verified
+    // against the actual bytes before any chunk is returned.
+    async readBundlePart(resultId, cursor, maxBytes = RESULT_CHUNK_MAX_BYTES) {
+        this.#requireOpen();
+        const payload = this.#cursor.decodeBundle(cursor);
+        if (payload.resultId !== resultId) {
+            throw artifactError("RESULT_CURSOR_MISMATCH", "The result cursor does not match this artifact.");
+        }
+        const manifest = await this.#loadBundleManifest(resultId);
+        if (payload.detail !== manifest.detail
+            || payload.groundingSchemaVersion !== GROUNDING_SCHEMA_VERSION
+            || payload.bundleProtocolVersion !== manifest.bundle_protocol_version
+            || payload.expiresAt !== manifest.expires_at) {
+            throw artifactError("RESULT_CURSOR_MISMATCH", "The result cursor does not match this artifact.");
+        }
+        const part = manifest.parts[payload.part];
+        if (part === undefined || payload.offset > part.result_bytes) {
+            throw artifactError("INVALID_RESULT_CURSOR", "The result cursor offset is invalid.");
+        }
+        let source;
+        if (part.storage.kind === "inline") {
+            // Inline parts are returned only through their closed descriptor
+            // storage shape (content text, or canonical JSON of the grounding
+            // value), never through a separate part file.
+            source = part.part === "content"
+                ? Buffer.from(part.storage.text, "utf8")
+                : (() => {
+                    try {
+                        return canonicalJson(part.storage.value);
+                    }
+                    catch {
+                        throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The local bundle part is invalid.");
+                    }
+                })();
+        }
+        else {
+            source = await readPrivateFile(path.join(this.#resultsDirectory, resultId, `${part.part}.data`), "LOCAL_RESULT_INTEGRITY_FAILED", "The local bundle part is missing.");
+        }
+        if (source.length !== part.result_bytes) {
+            throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The local bundle part is invalid.");
+        }
+        const computedDigest = `sha256:${createHash("sha256").update(source).digest("hex")}`;
+        if (computedDigest !== part.digest) {
+            throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The local bundle part is invalid.");
+        }
+        const normalizedMaxBytes = Number.isFinite(maxBytes)
+            ? Math.trunc(maxBytes)
+            : RESULT_CHUNK_MAX_BYTES;
+        const requested = Math.min(RESULT_CHUNK_MAX_BYTES, Math.max(1, normalizedMaxBytes));
+        const chunk = utf8SafeChunk(source, payload.offset, requested, part.result_bytes);
+        if (chunk.bytesRead === 0 && payload.offset < part.result_bytes) {
+            throw artifactError("RESULT_CHUNK_TOO_SMALL", "The requested result chunk cannot fit the next UTF-8 character.");
+        }
+        const nextOffset = payload.offset + chunk.bytesRead;
+        return {
+            resultId,
+            part: payload.part,
+            mediaType: part.media_type,
+            resultBytes: part.result_bytes,
+            offset: payload.offset,
+            decodedBytes: chunk.bytesRead,
+            text: chunk.text,
+            expiresAt: manifest.expires_at,
+            ...(nextOffset < part.result_bytes
+                ? {
+                    nextCursor: this.#cursor.encodeBundle({
+                        resultId,
+                        part: payload.part,
+                        detail: manifest.detail,
+                        groundingSchemaVersion: GROUNDING_SCHEMA_VERSION,
+                        bundleProtocolVersion: manifest.bundle_protocol_version,
+                        offset: nextOffset,
+                        expiresAt: manifest.expires_at,
+                    }),
+                }
+                : {}),
+        };
+    }
     async discard(resultId) {
         this.#requireOpen();
         if (!RESULT_ID_PATTERN.test(resultId))
@@ -433,9 +624,38 @@ export class ArtifactStore {
         const artifactPath = path.join(this.#resultsDirectory, `${resultId}.data`);
         const removedMetadata = await removeIfPresent(metadataPath);
         const removedArtifact = await removeIfPresent(artifactPath);
+        // Logical bundle: atomically rename the whole result directory out of the
+        // live namespace and fsync its parent first, so no reader can ever observe
+        // a half-live bundle; only then delete children and manifest. A cleanup
+        // failure leaves an inaccessible tombstone for startup cleanup and never
+        // reports a successful discard.
+        const directory = path.join(this.#resultsDirectory, resultId);
+        let bundleDetails;
+        try {
+            bundleDetails = await lstat(directory);
+        }
+        catch (error) {
+            if (!errno(error, "ENOENT"))
+                throw error;
+        }
+        if (bundleDetails !== undefined) {
+            if (!bundleDetails.isDirectory() || bundleDetails.isSymbolicLink()) {
+                throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The local result path is unsafe.");
+            }
+            const tombstone = path.join(this.#resultsDirectory, `${CLEANUP_PREFIX}${randomBytes(18).toString("base64url")}`);
+            await rename(directory, tombstone);
+            await syncDirectory(this.#resultsDirectory);
+            try {
+                await removeTree(tombstone);
+                await syncDirectory(this.#resultsDirectory);
+            }
+            catch {
+                throw artifactError("RESULT_DISCARD_FAILED", "The local result could not be discarded.", true);
+            }
+        }
         if (removedMetadata || removedArtifact)
             await syncDirectory(this.#resultsDirectory);
-        return removedMetadata || removedArtifact;
+        return removedMetadata || removedArtifact || bundleDetails !== undefined;
     }
     async cleanupExpired() {
         this.#requireOpen();
@@ -495,6 +715,38 @@ export class ArtifactStore {
                     removed += 1;
             }
         }
+        // Logical bundles: expire by manifest, and remove unreadable or orphaned
+        // bundle directories entirely.
+        for (const entry of entries) {
+            if (!entry.isDirectory() || !RESULT_ID_PATTERN.test(entry.name))
+                continue;
+            try {
+                const manifest = await this.#loadBundleManifest(entry.name, true);
+                if (Date.parse(manifest.expires_at) <= now) {
+                    if (await this.discard(entry.name))
+                        removed += 1;
+                }
+            }
+            catch {
+                if (await this.discard(entry.name))
+                    removed += 1;
+            }
+        }
+        // Inaccessible cleanup tombstones from failed discards: restore
+        // permissions and finish the removal at startup.
+        for (const entry of entries) {
+            if (!entry.isDirectory() || !CLEANUP_NAME_PATTERN.test(entry.name))
+                continue;
+            const entryPath = path.join(this.#resultsDirectory, entry.name);
+            try {
+                await chmod(entryPath, 0o700);
+                await removeTree(entryPath);
+                removed += 1;
+            }
+            catch {
+                // Leave the inaccessible tombstone for a future startup cleanup.
+            }
+        }
         if (removed > 0)
             await syncDirectory(this.#resultsDirectory);
         return removed;
@@ -566,6 +818,53 @@ export class ArtifactStore {
             throw error;
         }
     }
+    // Install a verified bundle as one private per-result directory: durable
+    // content and grounding children first, then the closed manifest as the
+    // commit point. Every file and its containing directory are fsynced before
+    // success; on failure the directory is removed best-effort and the error
+    // propagates so the retention sink reports nothing durable.
+    async _finalizeBundle(resultId, verified, metadata) {
+        const now = this.#now();
+        const createdAt = now.toISOString();
+        const expiresAt = new Date(now.getTime() + this.#retentionMs).toISOString();
+        const directory = path.join(this.#resultsDirectory, resultId);
+        const contentPath = path.join(directory, "content.data");
+        const groundingPath = path.join(directory, "grounding.data");
+        const manifestPath = path.join(directory, "manifest.json");
+        try {
+            await mkdir(directory, { mode: 0o700 });
+            await syncDirectory(this.#resultsDirectory);
+            if (!await installPrivateBytes(directory, contentPath, verified.content.bytes)) {
+                throw artifactError("LOCAL_ARTIFACT_FAILED", "The local bundle part could not be installed.");
+            }
+            if (!await installPrivateBytes(directory, groundingPath, verified.grounding.bytes)) {
+                throw artifactError("LOCAL_ARTIFACT_FAILED", "The local bundle part could not be installed.");
+            }
+            const manifest = {
+                version: BUNDLE_MANIFEST_VERSION,
+                kind: "bundle",
+                result_id: resultId,
+                detail: verified.detail,
+                bundle_protocol_version: RESULT_BUNDLE_PROTOCOL_VERSION,
+                bundle_digest: verified.bundleDigest,
+                bundle_bytes: verified.bundleBytes,
+                created_at: createdAt,
+                expires_at: expiresAt,
+                parts: {
+                    content: this.#partManifest("content", resultId, verified, expiresAt),
+                    grounding: this.#partManifest("grounding", resultId, verified, expiresAt),
+                },
+            };
+            if (!await installPrivateBytes(directory, manifestPath, Buffer.from(JSON.stringify(manifest), "utf8"))) {
+                throw artifactError("LOCAL_ARTIFACT_FAILED", "The local bundle manifest could not be installed.");
+            }
+            return this.#bundleResult(metadata, manifest);
+        }
+        catch (error) {
+            await removeTree(directory).catch(() => { });
+            throw error;
+        }
+    }
     async _newTemporaryArtifact() {
         this.#requireOpen();
         for (let attempt = 0; attempt < 8; attempt += 1) {
@@ -619,6 +918,122 @@ export class ArtifactStore {
         }
         return metadata;
     }
+    async #hasBundleDirectory(resultId) {
+        const directory = path.join(this.#resultsDirectory, resultId);
+        let details;
+        try {
+            details = await lstat(directory);
+        }
+        catch (error) {
+            if (errno(error, "ENOENT"))
+                return false;
+            throw error;
+        }
+        if (!details.isDirectory() || details.isSymbolicLink()) {
+            throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The local result path is unsafe.");
+        }
+        return true;
+    }
+    async #loadBundleManifest(resultId, allowExpired = false) {
+        if (!RESULT_ID_PATTERN.test(resultId)) {
+            throw artifactError("RESULT_NOT_FOUND", "The local result artifact is unavailable.");
+        }
+        const manifestPath = path.join(this.#resultsDirectory, resultId, "manifest.json");
+        let value;
+        try {
+            const bytes = await readPrivateFile(manifestPath, "RESULT_NOT_FOUND", "The local result artifact is unavailable.");
+            value = JSON.parse(bytes.toString("utf8"));
+        }
+        catch (error) {
+            if (error instanceof SyntaxError) {
+                throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The local bundle manifest is invalid.");
+            }
+            throw error;
+        }
+        let manifest;
+        try {
+            manifest = bundleManifestSchema.parse(value);
+        }
+        catch {
+            throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The local bundle manifest is invalid.");
+        }
+        if (manifest.result_id !== resultId) {
+            throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The local bundle manifest is invalid.");
+        }
+        if (!allowExpired && Date.parse(manifest.expires_at) <= this.#now().getTime()) {
+            await this.discard(resultId);
+            throw artifactError("RESULT_EXPIRED", "The local result artifact has expired.");
+        }
+        return manifest;
+    }
+    #partManifest(part, resultId, verified, expiresAt) {
+        const partInfo = part === "content" ? verified.content : verified.grounding;
+        const storage = partInfo.bytes.length <= INLINE_RESULT_MAX_BYTES
+            ? (part === "content"
+                ? { kind: "inline", text: partInfo.bytes.toString("utf8") }
+                : { kind: "inline", value: verified.grounding.value })
+            : {
+                kind: "artifact",
+                // Initial artifact cursors always use offset 0.
+                next_cursor: this.#cursor.encodeBundle({
+                    resultId,
+                    part,
+                    detail: verified.detail,
+                    groundingSchemaVersion: GROUNDING_SCHEMA_VERSION,
+                    bundleProtocolVersion: RESULT_BUNDLE_PROTOCOL_VERSION,
+                    offset: 0,
+                    expiresAt,
+                }),
+            };
+        return {
+            part,
+            media_type: partInfo.mediaType,
+            result_bytes: partInfo.bytes.length,
+            digest: partInfo.digest,
+            storage,
+        };
+    }
+    #bundleResult(metadata, manifest) {
+        const contentStorage = () => {
+            const stored = manifest.parts.content.storage;
+            return stored.kind === "inline"
+                ? { kind: "inline", text: stored.text }
+                : { kind: "artifact", nextCursor: stored.next_cursor };
+        };
+        const groundingStorage = () => {
+            const stored = manifest.parts.grounding.storage;
+            return stored.kind === "inline"
+                ? { kind: "inline", value: stored.value }
+                : { kind: "artifact", nextCursor: stored.next_cursor };
+        };
+        return {
+            kind: "bundle",
+            operationId: metadata.operationId,
+            resultId: manifest.result_id,
+            detail: manifest.detail,
+            bundleBytes: manifest.bundle_bytes,
+            bundleDigest: manifest.bundle_digest,
+            expiresAt: manifest.expires_at,
+            bundleProtocolVersion: manifest.bundle_protocol_version,
+            groundingSchemaVersion: GROUNDING_SCHEMA_VERSION,
+            parts: {
+                content: {
+                    part: "content",
+                    mediaType: manifest.parts.content.media_type,
+                    resultBytes: manifest.parts.content.result_bytes,
+                    digest: manifest.parts.content.digest,
+                    storage: contentStorage(),
+                },
+                grounding: {
+                    part: "grounding",
+                    mediaType: manifest.parts.grounding.media_type,
+                    resultBytes: manifest.parts.grounding.result_bytes,
+                    digest: manifest.parts.grounding.digest,
+                    storage: groundingStorage(),
+                },
+            },
+        };
+    }
     #requireOpen() {
         if (this.#closed)
             throw cacheError("ARTIFACT_STORE_CLOSED", "The local artifact store is closed.");
@@ -633,6 +1048,7 @@ export class LocalResultRetention {
     #received = 0;
     #artifact;
     #result;
+    #bundle;
     constructor(store) {
         this.#store = store;
     }
@@ -642,7 +1058,7 @@ export class LocalResultRetention {
         this.#result = undefined;
     }
     async begin(metadata) {
-        if (this.#start !== undefined || this.#result !== undefined) {
+        if (this.#start !== undefined || this.#result !== undefined || this.#bundle !== undefined) {
             throw artifactError("LOCAL_RESULT_STATE_INVALID", "Local result retention has already started.");
         }
         if (!Number.isSafeInteger(metadata.resultBytes)
@@ -697,7 +1113,11 @@ export class LocalResultRetention {
         const start = this.#start;
         const hash = this.#hash;
         const decoder = this.#decoder;
-        if (start === undefined || hash === undefined || decoder === undefined || this.#result !== undefined) {
+        if (start === undefined
+            || hash === undefined
+            || decoder === undefined
+            || this.#result !== undefined
+            || this.#bundle !== undefined) {
             throw artifactError("LOCAL_RESULT_STATE_INVALID", "Local result retention cannot be completed.");
         }
         try {
@@ -732,6 +1152,20 @@ export class LocalResultRetention {
             await handle.sync();
             await handle.close();
             artifact.handle = undefined;
+            if (start.mediaType === BUNDLE_MEDIA_TYPE) {
+                // Bundle retention: verify the full remote bytes against the declared
+                // digest, then run strict canonical bundle validation, and only after
+                // every part passes install the durable children and closed manifest.
+                const bytes = await readPrivateFile(artifact.temporaryPath, "LOCAL_RESULT_INTEGRITY_FAILED", "The retained bundle is incomplete.");
+                if (bytes.length !== start.resultBytes) {
+                    throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The retained bundle is incomplete.");
+                }
+                const verified = verifyResultBundle(bytes);
+                const stored = await this.#store._finalizeBundle(artifact.resultId, verified, metadata);
+                await removeIfPresent(artifact.temporaryPath);
+                this.#bundle = stored;
+                return;
+            }
             const stored = await this.#store._finalizeArtifact(artifact.temporaryPath, {
                 ...metadata,
                 resultId: artifact.resultId,
@@ -759,11 +1193,20 @@ export class LocalResultRetention {
         }
     }
     result() {
+        if (this.#bundle !== undefined) {
+            throw artifactError("LOCAL_RESULT_STATE_INVALID", "The local bundle result cannot be returned as text.");
+        }
         if (this.#result === undefined) {
             throw artifactError("LOCAL_RESULT_NOT_DURABLE", "The local result has not been retained durably.");
         }
         return this.#result;
     }
+    bundleResult() {
+        if (this.#bundle === undefined) {
+            throw artifactError("LOCAL_RESULT_NOT_DURABLE", "The local result has not been retained durably.");
+        }
+        return this.#bundle;
+    }
     async abort() {
         const artifact = this.#artifact;
         if (artifact?.handle !== undefined) {
@@ -779,5 +1222,6 @@ export class LocalResultRetention {
         this.#decoder = undefined;
         this.#received = 0;
         this.#result = undefined;
+        this.#bundle = undefined;
     }
 }

package/dist/capabilities.d.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+export declare const READER_CAPABILITIES_PROTOCOL = "omni.reader_capabilities.v1";
+export type RequestedDetail = "grounded" | "layout";
+declare const directProfileSchema: z.ZodObject<{
+    profile: z.ZodLiteral<"omni.direct_grounding.v1">;
+    grant_protocol: z.ZodLiteral<"omni.parse_grant.v3">;
+    stream_protocol: z.ZodLiteral<"omni.granted_parse_stream.v2">;
+    operation_protocol: z.ZodLiteral<"omni.direct_operation.v2">;
+    settlement_protocol: z.ZodLiteral<"omni.grant_settlement.v4">;
+    release_protocol: z.ZodLiteral<"omni.release_decision.v2">;
+    settlement_journal_protocol: z.ZodLiteral<"omni.direct_settlement_journal.v2">;
+    usage_protocol: z.ZodLiteral<"omni_parse_usage.v2">;
+    billing_protocol: z.ZodLiteral<"omni_billing.v2">;
+    bridge_protocol: z.ZodLiteral<"omni.local_bridge_tools.v3">;
+    bundle_protocol: z.ZodLiteral<"omni.result_bundle.v1">;
+    grounding_schema: z.ZodLiteral<"omni.grounding.v1">;
+    details: z.ZodTuple<[z.ZodLiteral<"grounded">, z.ZodLiteral<"layout">], null>;
+    max_result_bytes: z.ZodLiteral<67108864>;
+}, "strict", z.ZodTypeAny, {
+    profile: "omni.direct_grounding.v1";
+    grant_protocol: "omni.parse_grant.v3";
+    stream_protocol: "omni.granted_parse_stream.v2";
+    operation_protocol: "omni.direct_operation.v2";
+    settlement_protocol: "omni.grant_settlement.v4";
+    release_protocol: "omni.release_decision.v2";
+    settlement_journal_protocol: "omni.direct_settlement_journal.v2";
+    usage_protocol: "omni_parse_usage.v2";
+    billing_protocol: "omni_billing.v2";
+    bridge_protocol: "omni.local_bridge_tools.v3";
+    bundle_protocol: "omni.result_bundle.v1";
+    grounding_schema: "omni.grounding.v1";
+    details: ["grounded", "layout"];
+    max_result_bytes: 67108864;
+}, {
+    profile: "omni.direct_grounding.v1";
+    grant_protocol: "omni.parse_grant.v3";
+    stream_protocol: "omni.granted_parse_stream.v2";
+    operation_protocol: "omni.direct_operation.v2";
+    settlement_protocol: "omni.grant_settlement.v4";
+    release_protocol: "omni.release_decision.v2";
+    settlement_journal_protocol: "omni.direct_settlement_journal.v2";
+    usage_protocol: "omni_parse_usage.v2";
+    billing_protocol: "omni_billing.v2";
+    bridge_protocol: "omni.local_bridge_tools.v3";
+    bundle_protocol: "omni.result_bundle.v1";
+    grounding_schema: "omni.grounding.v1";
+    details: ["grounded", "layout"];
+    max_result_bytes: 67108864;
+}>;
+declare const urlProfileSchema: z.ZodObject<{
+    profile: z.ZodLiteral<"omni.url_grounding.v1">;
+    operation_protocol: z.ZodLiteral<"omni.url_operation.v3">;
+    usage_protocol: z.ZodLiteral<"omni_parse_usage.v2">;
+    billing_protocol: z.ZodLiteral<"omni_billing.v2">;
+    bridge_protocol: z.ZodLiteral<"omni.local_bridge_tools.v3">;
+    bundle_protocol: z.ZodLiteral<"omni.result_bundle.v1">;
+    grounding_schema: z.ZodLiteral<"omni.grounding.v1">;
+    details: z.ZodTuple<[z.ZodLiteral<"grounded">, z.ZodLiteral<"layout">], null>;
+    max_result_bytes: z.ZodLiteral<16777216>;
+}, "strict", z.ZodTypeAny, {
+    profile: "omni.url_grounding.v1";
+    operation_protocol: "omni.url_operation.v3";
+    usage_protocol: "omni_parse_usage.v2";
+    billing_protocol: "omni_billing.v2";
+    bridge_protocol: "omni.local_bridge_tools.v3";
+    bundle_protocol: "omni.result_bundle.v1";
+    grounding_schema: "omni.grounding.v1";
+    details: ["grounded", "layout"];
+    max_result_bytes: 16777216;
+}, {
+    profile: "omni.url_grounding.v1";
+    operation_protocol: "omni.url_operation.v3";
+    usage_protocol: "omni_parse_usage.v2";
+    billing_protocol: "omni_billing.v2";
+    bridge_protocol: "omni.local_bridge_tools.v3";
+    bundle_protocol: "omni.result_bundle.v1";
+    grounding_schema: "omni.grounding.v1";
+    details: ["grounded", "layout"];
+    max_result_bytes: 16777216;
+}>;
+export type DirectProfileV1 = z.infer<typeof directProfileSchema>;
+export type UrlProfileV1 = z.infer<typeof urlProfileSchema>;
+export interface ReaderCapabilitiesV1 {
+    readonly protocol_version: typeof READER_CAPABILITIES_PROTOCOL;
+    readonly expires_at: Date;
+    readonly direct_profiles: readonly DirectProfileV1[];
+    readonly url_profiles: readonly UrlProfileV1[];
+}
+export declare function parseReaderCapabilities(value: unknown, now: Date): ReaderCapabilitiesV1;
+export declare function selectDirectProfile(value: ReaderCapabilitiesV1, detail: RequestedDetail): DirectProfileV1;
+export declare function selectUrlProfile(value: ReaderCapabilitiesV1, detail: RequestedDetail): UrlProfileV1;
+export {};