@vibesdotdev/docs 0.0.0-stage → 1.0.0-rc.2

package/dist/documents/tools/document-read.impl.js

@@ -0,0 +1,1139 @@
+/**
+ * document.read tool implementation.
+ *
+ * Cache-first orchestration for document reading:
+ *   1. Build a cache key from (ref, page, renderProfile, promptVersion)
+ *   2. Look up in the documents.page-cache manifest
+ *   3. Cache hit  → return stored markdown (+ cached rows when a schema read)
+ *   4. Cache miss → render the page PNG once via the scope-injected renderer
+ *                 → POST ai-web /api/internal/ocr (VISION OCR on the PNG) → markdown
+ *                 → when input.schema is set, ALSO POST ai-web
+ *                   /api/internal/document-extract (VISION extract on the SAME
+ *                   PNG) → rows
+ *                 → write markdown (+ rows) to the cache
+ *
+ * The rendered PNG is produced ONCE per page and fed to BOTH internal calls —
+ * extract is a vision read on the page image, not a re-parse of the OCR markdown.
+ *
+ * HTTP contracts (reconciled to the LIVE ai-web routes):
+ *
+ *   OCR endpoint — VISION OCR on a rasterized page image:
+ *     POST ${aiOrigin}/api/internal/ocr
+ *     Headers: Authorization: Bearer ${VIBES_INTERNAL_SERVICE_TOKEN}
+ *              Content-Type: application/json
+ *     Body: { image: string (raw base64 PNG), mimeType?, category?,
+ *             modelId?, modelName?, prompt? }
+ *     Response: { text: string, markdown: string, metadata: Record<string, unknown> }
+ *     (Source: apps/ai-web/src/routes/api/internal/ocr/+server.ts)
+ *
+ *   Extract endpoint — schema-driven VISION extract on the SAME page image:
+ *     POST ${aiOrigin}/api/internal/document-extract
+ *     Headers: Authorization: Bearer ${VIBES_INTERNAL_SERVICE_TOKEN}
+ *              Content-Type: application/json
+ *     Body: { image: string (raw base64 PNG), mimeType?, schema (REQUIRED),
+ *             vocabulary?: string[], rowContainerKeys?: string[], promptHint?: string, modelId?, modelName? }
+ *     Response: { rows: unknown[], raw: string, diagnostics: Record<string, unknown> }
+ *     (Source: apps/ai-web/src/routes/api/internal/document-extract/+server.ts)
+ *
+ * NOTE: there is no markdown-analyzer endpoint. When input.question is set WITHOUT
+ * input.schema, the impl returns the markdown path — the calling agent reads the
+ * page markdown to answer the question. A schema is required to get structured rows.
+ *
+ * A ref's `sourceRefreshUrl` is admitted against the declared destinations before
+ * the internal service credential goes to it (`./source-refresh.ts`).
+ *
+ * TODO(WS0): Wire VIBES_PDF_RENDER_ORIGIN for the consumer-scope renderer.
+ * TODO(WS0): Wire the platform CRUD endpoint /api/documents/page-cache (cloud-api adapter).
+ */
+import * as z from 'zod/v4';
+import { CapabilityError, isCapabilityError, valueFreeFailure, settle, settleNow } from '@vibesdotdev/kernel';
+import { getLogger } from '@vibesdotdev/logging';
+import { JsonObjectSchema, JsonValueSchema } from '@vibesdotdev/kernel/schemas/json';
+import { StorageManifest } from '@vibesdotdev/storage';
+import { readTrustedRunContext } from '@vibesdotdev/tools/agents/trusted-context';
+import { serviceOrigin } from '@vibesdotdev/infra-core/service';
+import { PDF_OCR_FOVEATE_PAGE_JOB_ID, PDF_OCR_QUEUE_ID } from '@vibesdotdev/ai/generation/pdf-ocr';
+import { DocumentReadInputSchema } from "../schemas/document-read.schema.js";
+import { DocumentPageCacheRecordSchema } from "../schemas/page-cache.schema.js";
+import { planFoveationGrid, enumerateGridCells, cellsAreAdjacent, FOVEATE_DEFAULT_OVERLAP, FOVEATE_MAX_CELLS, FOVEATE_MIN_LONGEST_EDGE_PX } from "../render/grid.js";
+import { resolveFreshSourceUrl, resolveInternalServiceToken } from "./source-refresh.js";
+import { AIServiceBindingSchema } from "../schemas/ai-service-binding.schema.js";
+// ---------------------------------------------------------------------------
+// Cache key
+// ---------------------------------------------------------------------------
+/**
+ * Build a stable cache key for a (ref, page, renderProfile, promptVersion)
+ * tuple. Used to look up and write records in the documents.page-cache manifest.
+ */
+export function buildCacheKey(ref, page, renderProfile, promptVersion) {
+    const stableExternalId = ref.documentId ? `document:${ref.documentId}` : ref.url ?? '';
+    const refPart = [ref.providerId ?? '', ref.path ?? '', stableExternalId].join('|');
+    return `${refPart}::p${page}::${renderProfile}::${promptVersion}`;
+}
+async function sha256Hex(input) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(input));
+    return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+export async function buildFoveatedPageJobId(storageCacheKey) {
+    return `pdf-ocr-foveate:${await sha256Hex(storageCacheKey)}`;
+}
+// ---------------------------------------------------------------------------
+// Prompt folding
+// ---------------------------------------------------------------------------
+/**
+ * The live OCR endpoint exposes a SINGLE `prompt` field (no separate
+ * instructions / visionFocusHint / vocabulary fields). Fold the focus hint and
+ * freeform instructions into one prompt string, or undefined when neither is set.
+ */
+function foldOcrPrompt(input) {
+    const parts = [];
+    if (input.visionFocusHint)
+        parts.push(`[focus] ${input.visionFocusHint}`);
+    if (input.instructions)
+        parts.push(input.instructions);
+    return parts.length > 0 ? parts.join('\n') : undefined;
+}
+// ---------------------------------------------------------------------------
+// Internal HTTP helpers — reconciled to the live ai-web route schemas.
+// ---------------------------------------------------------------------------
+/** Live /api/internal/ocr response shape. */
+const OcrResponseSchema = z.object({
+    text: z.string(),
+    markdown: z.string(),
+    metadata: z.record(z.string(), JsonValueSchema).default({})
+});
+/** Live /api/internal/document-extract response shape. */
+const ExtractResponseSchema = z.object({
+    rows: z.array(JsonValueSchema).default([]),
+    raw: z.string().default(''),
+    diagnostics: z.record(z.string(), JsonValueSchema).default({})
+});
+/**
+ * The ai-web origin that serves /api/internal/ocr + /api/internal/document-extract:
+ * the declared `ai` service's internal origin. document.read runs on ai-web or on
+ * any app loading the documents plugin; both select the same service catalog, so
+ * there is no self-origin special case.
+ */
+async function resolveAiInternalOrigin(runtime) {
+    return (await serviceOrigin(runtime, 'ai', 'internal')).replace(/\/$/, '');
+}
+/**
+ * Fetch the ai-web internal endpoints WITHOUT going through the public edge.
+ *
+ * document.read runs ON ai-web, so calling `fetch('https://ai.vibes.dev/...')`
+ * is a self-loopback over the Cloudflare edge — which times the OCR subrequest
+ * out and returns a 522 (the same "never self-fetch a public hostname" trap that
+ * broke cron). When the `AI_INTERNAL` service binding (a worker-to-self Fetcher
+ * declared in ai-web's deployment.config) is present we route through it instead:
+ * the request goes worker→worker with no edge hop, so a slow vision-OCR call
+ * completes within the tool budget instead of hitting the edge timeout. The URL
+ * host is ignored by the service binding (it routes to vibes-ai); only the path
+ * matters. Falls back to the global fetch for any app consuming ai-web remotely.
+ */
+function internalFetch(runtime, url, init) {
+    const binding = runtime.getBinding('AI_INTERNAL', AIServiceBindingSchema);
+    if (binding)
+        return binding.fetch(url, init);
+    return fetch(url, init);
+}
+async function callOcr(runtime, aiOrigin, token, body) {
+    const response = await internalFetch(runtime, `${aiOrigin}/api/internal/ocr`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(body)
+    });
+    if (!response.ok) {
+        throw new CapabilityError('Document OCR request refused.', 'UNAVAILABLE', { reason: 'document-ocr-failed', details: { status: response.status } });
+    }
+    return OcrResponseSchema.parse(await response.json());
+}
+async function callExtract(runtime, aiOrigin, token, body) {
+    const response = await internalFetch(runtime, `${aiOrigin}/api/internal/document-extract`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(body)
+    });
+    if (!response.ok) {
+        throw new CapabilityError('Document extraction request refused.', 'UNAVAILABLE', { reason: 'document-extract-failed', details: { status: response.status } });
+    }
+    return ExtractResponseSchema.parse(await response.json());
+}
+/** The page cache manifest of `runtime`, the runtime the tool call was handed. */
+function getPageCache(runtime) {
+    return StorageManifest.fromId('documents.page-cache', runtime);
+}
+function readString(value) {
+    const parsed = z.string().safeParse(value);
+    if (!parsed.success)
+        return undefined;
+    const trimmed = parsed.data.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function resolveRequestOwner(runtime, ctx) {
+    // Identity is per invocation: the active invocation's actor (rc01 §2.1).
+    const principal = runtime.scope.actor;
+    const metadata = readTrustedRunContext(ctx);
+    const userId = readString(metadata.userId) ?? principal?.userId;
+    if (!userId)
+        return null;
+    const organizationId = readString(metadata.orgId) ?? principal?.orgId;
+    const owner = { userId };
+    if (organizationId)
+        owner.organizationId = organizationId;
+    return owner;
+}
+async function tryResolvePlatformOrigin(runtime) {
+    return settle(async () => (await serviceOrigin(runtime, 'platform', 'internal')).replace(/\/$/, ''));
+}
+/**
+ * The declared `platform` service's internal origin for the page cache, or
+ * `null` when this host declares no `platform` service for its service environment (`service-undeclared`:
+ * the page cache is an optimisation and stays off). Any other failure throws.
+ */
+async function resolvePlatformOrigin(runtime) {
+    const res = await tryResolvePlatformOrigin(runtime);
+    if (res.ok)
+        return res.value;
+    if (res.cause instanceof Error && isCapabilityError(res.cause) && res.cause.reason === 'service-undeclared') {
+        return null;
+    }
+    throw res.cause;
+}
+const PageCacheLookupResponseSchema = z.object({
+    result: JsonValueSchema.optional()
+});
+async function createInternalPageCacheClient(runtime, ctx, token) {
+    const owner = resolveRequestOwner(runtime, ctx);
+    const platformOrigin = await resolvePlatformOrigin(runtime);
+    if (!owner || !platformOrigin)
+        return null;
+    const headers = () => {
+        const h = {
+            authorization: `Bearer ${token}`,
+            'x-vibes-user-id': owner.userId,
+            'content-type': 'application/json',
+            origin: platformOrigin
+        };
+        if (owner.organizationId) {
+            h['x-vibes-organization-id'] = owner.organizationId;
+        }
+        return h;
+    };
+    const ownerType = owner.organizationId ? 'organization' : 'user';
+    const ownerId = owner.organizationId ?? owner.userId;
+    const storageKey = (cacheKey) => `${ownerType}:${encodeURIComponent(ownerId)}:${cacheKey}`;
+    return {
+        async lookup(cacheKey) {
+            const key = storageKey(cacheKey);
+            const response = await fetch(`${platformOrigin}/api/internal/documents/page-cache/${encodeURIComponent(key)}`, { headers: headers() });
+            if (response.status === 404)
+                return null;
+            if (!response.ok)
+                throw new Error(`page-cache lookup failed (${response.status})`);
+            const data = PageCacheLookupResponseSchema.safeParse(await response.json());
+            const parsed = data.success && data.data.result ? DocumentPageCacheRecordSchema.safeParse(data.data.result) : null;
+            return parsed?.success ? parsed.data : null;
+        },
+        async write(record) {
+            const stored = { ...record, id: storageKey(record.id) };
+            const response = await fetch(`${platformOrigin}/api/internal/documents/page-cache/${encodeURIComponent(stored.id)}`, {
+                method: 'PUT',
+                headers: headers(),
+                body: JSON.stringify(stored)
+            });
+            if (!response.ok) {
+                throw new CapabilityError('Document page-cache write refused.', 'UNAVAILABLE', { reason: 'document-cache-write-failed', details: { status: response.status } });
+            }
+        },
+        storageKey
+    };
+}
+async function safeLoadCacheRecords(cache) {
+    return settle(async () => (await cache.load()) ?? []);
+}
+function createManifestPageCacheClient(cache, runtime) {
+    return {
+        async lookup(cacheKey) {
+            const res = await safeLoadCacheRecords(cache);
+            if (res.ok) {
+                return res.value.find((r) => r.id === cacheKey) ?? null;
+            }
+            const diagnostic = settleNow(() => getLogger('documents.read', runtime).warn('page-cache manifest lookup failed; treating as a miss', {
+                cacheKey,
+                error: valueFreeFailure(res.cause)
+            }));
+            if (!diagnostic.ok)
+                settleNow(() => runtime.diagnostics.error('Document diagnostic failed', { scope: 'docs', plugin: 'documents.read', error: new AggregateError([res.cause, diagnostic.cause], 'Primary failure and diagnostic failed.', { cause: res.cause }) }));
+            return null;
+        },
+        async write(record) {
+            const res = await safeLoadCacheRecords(cache);
+            const records = res.ok ? res.value : [];
+            const idx = records.findIndex((r) => r.id === record.id);
+            if (idx >= 0) {
+                records[idx] = record;
+            }
+            else {
+                records.push(record);
+            }
+            await cache.save(records);
+        },
+        storageKey(cacheKey) {
+            return cacheKey;
+        }
+    };
+}
+async function tryCreateInternalPageCacheClient(runtime, ctx, token) {
+    return settle(() => createInternalPageCacheClient(runtime, ctx, token));
+}
+async function resolvePageCacheClient(runtime, ctx, token) {
+    const res = await tryCreateInternalPageCacheClient(runtime, ctx, token);
+    if (res.ok && res.value)
+        return res.value;
+    if (!res.ok) {
+        const diagnostic = settleNow(() => getLogger('documents.read', runtime).warn('internal page-cache client unavailable; using the manifest adapter', {
+            error: valueFreeFailure(res.cause)
+        }));
+        if (!diagnostic.ok)
+            settleNow(() => runtime.diagnostics.error('Document diagnostic failed', { scope: 'docs', plugin: 'documents.read', error: new AggregateError([res.cause, diagnostic.cause], 'Primary failure and diagnostic failed.', { cause: res.cause }) }));
+    }
+    return createManifestPageCacheClient(getPageCache(runtime), runtime);
+}
+async function tryLookupCache(cache, cacheKey) {
+    return settle(() => cache.lookup(cacheKey));
+}
+async function lookupCache(cache, cacheKey, runtime) {
+    const res = await tryLookupCache(cache, cacheKey);
+    if (res.ok)
+        return res.value;
+    const diagnostic = settleNow(() => getLogger('documents.read', runtime).warn('page-cache lookup failed; treating as a miss', {
+        cacheKey,
+        error: valueFreeFailure(res.cause)
+    }));
+    if (!diagnostic.ok)
+        settleNow(() => runtime.diagnostics.error('Document diagnostic failed', { scope: 'docs', plugin: 'documents.read', error: new AggregateError([res.cause, diagnostic.cause], 'Primary failure and diagnostic failed.', { cause: res.cause }) }));
+    return null;
+}
+async function writeCache(cache, record) {
+    await cache.write(record);
+}
+// ---------------------------------------------------------------------------
+// Core per-page logic
+// ---------------------------------------------------------------------------
+const DEFAULT_RENDER_PROFILE = 'page-150dpi';
+// CACHE-BUST: the page cache keys on (ref, page, renderProfile, promptVersion) — NOT on the
+// extraction-schema descriptor version or the preamble text. So ANY change to the casework
+// estimator preamble / cabinet schema (the drawing-literacy, quantity-semantics, non-casework
+// rules) MUST bump this token, or a previously-cached page is re-served with the STALE prompt
+// and the fix silently never applies. Bump on every prompt/schema change. (v2 = reconciliation
+// fixes: quantity≠N-units, non-casework describe-not-counter, multi-view transcription.)
+const DEFAULT_PROMPT_VERSION = 'v4-describe-foveate';
+const ASYNC_PROCESSING_MESSAGE = 'foveated read queued — re-read this page to retrieve the transcription once processing completes.';
+const ASYNC_ERROR_MESSAGE = 'foveated read failed in the background — re-read this page in a few minutes to retry it.';
+const PROCESSING_MARKER_STALE_MS = 30 * 60 * 1000;
+/**
+ * Cool-off before a cached FAILURE marker becomes retryable. Within the
+ * window the error is served as-is (so an agent loop cannot hot-requeue a
+ * failing page); after it, a re-read falls through to a fresh render +
+ * re-enqueue with a FRESH source URL — background failures (expired
+ * SharePoint tempauth, transient model outages, capacity) must never be
+ * permanent just because they were cached.
+ */
+const ERROR_MARKER_RETRY_MS = 5 * 60 * 1000;
+export function isProcessingCacheRecord(record) {
+    return (record.quality?.asyncStatus === 'processing' ||
+        record.ocrMarkdown.includes(ASYNC_PROCESSING_MESSAGE));
+}
+export function isStaleProcessingCacheRecord(record, nowMs = Date.now()) {
+    if (!isProcessingCacheRecord(record))
+        return false;
+    const queuedAt = readString(record.quality?.queuedAt);
+    if (!queuedAt)
+        return false;
+    const queuedAtMs = Date.parse(queuedAt);
+    if (!Number.isFinite(queuedAtMs))
+        return false;
+    return nowMs - queuedAtMs > PROCESSING_MARKER_STALE_MS;
+}
+function isErrorCacheRecord(record) {
+    return record.quality?.asyncStatus === 'error';
+}
+/** A failure marker older than the cool-off (or missing/garbled failedAt —
+ *  legacy rows) is retryable: the read path re-renders + re-enqueues. */
+export function isRetryableErrorCacheRecord(record, nowMs = Date.now()) {
+    if (!isErrorCacheRecord(record))
+        return false;
+    const failedAt = readString(record.quality?.failedAt);
+    if (!failedAt)
+        return true;
+    const failedAtMs = Date.parse(failedAt);
+    if (!Number.isFinite(failedAtMs))
+        return true;
+    return nowMs - failedAtMs > ERROR_MARKER_RETRY_MS;
+}
+function processingPage(page, cacheKey, jobId) {
+    const res = {
+        index: page,
+        text: ASYNC_PROCESSING_MESSAGE,
+        cacheHit: false,
+        status: 'processing',
+        cacheKey,
+        message: ASYNC_PROCESSING_MESSAGE
+    };
+    if (jobId)
+        res.jobId = jobId;
+    return res;
+}
+function errorPage(page, cacheKey, record) {
+    const message = readString(record.quality?.message) ?? ASYNC_ERROR_MESSAGE;
+    const jobId = readString(record.quality?.jobId);
+    const res = {
+        index: page,
+        text: record.ocrMarkdown || message,
+        cacheHit: true,
+        status: 'error',
+        cacheKey,
+        message
+    };
+    if (jobId)
+        res.jobId = jobId;
+    return res;
+}
+function asyncFoveationEnabled(runtime, input) {
+    if (input.schema)
+        return false;
+    const forceSync = runtime.getEnv('VIBES_DOCUMENT_READ_SYNC_FOVEATION');
+    if (forceSync === '1' || forceSync === 'true' || forceSync === 'TRUE')
+        return false;
+    const disabled = runtime.getEnv('VIBES_DOCUMENT_READ_ASYNC_FOVEATION');
+    return !(disabled === '0' || disabled === 'false' || disabled === 'FALSE');
+}
+async function resolvePdfOcrQueue(runtime) {
+    const res = await settle(async () => {
+        const adapter = await runtime
+            .query('workers/adapter')
+            .withId('worker-adapter.kafka')
+            .resolve();
+        if (!adapter?.getQueueAdapter) {
+            throw new Error('Adapter worker-adapter.kafka missing getQueueAdapter');
+        }
+        if (adapter.isConnected && !adapter.isConnected()) {
+            await adapter.connect?.(runtime);
+        }
+        const queue = adapter.getQueueAdapter(PDF_OCR_QUEUE_ID);
+        await queue.connect?.();
+        return queue;
+    });
+    if (!res.ok) {
+        const diagnostic = settleNow(() => getLogger('documents.read', runtime).warn('pdf-ocr queue unavailable; falling back to synchronous foveation', {
+            error: valueFreeFailure(res.cause)
+        }));
+        if (!diagnostic.ok)
+            settleNow(() => runtime.diagnostics.error('Document diagnostic failed', { scope: 'docs', plugin: 'documents.read', error: new AggregateError([res.cause, diagnostic.cause], 'Primary failure and diagnostic failed.', { cause: res.cause }) }));
+    }
+    return res;
+}
+async function writeProcessingMarker(args) {
+    const quality = {
+        asyncStatus: 'processing',
+        cacheKey: args.cacheKey,
+        queuedAt: new Date().toISOString()
+    };
+    if (args.jobId)
+        quality.jobId = args.jobId;
+    await writeCache(args.cache, {
+        id: args.cacheKey,
+        ref: args.input.ref,
+        page: args.page,
+        renderProfile: args.renderProfile,
+        promptVersion: args.promptVersion,
+        ocrMarkdown: ASYNC_PROCESSING_MESSAGE,
+        quality,
+        sourceHash: `processing:${args.jobId ?? args.cacheKey}`,
+        renderedAt: new Date().toISOString()
+    });
+}
+async function tryWriteProcessingMarker(args) {
+    return settle(async () => {
+        await writeProcessingMarker(args);
+    });
+}
+async function enqueueFoveatedPage(args) {
+    const owner = resolveRequestOwner(args.runtime, args.ctx);
+    if (!owner)
+        return null;
+    const platformOrigin = await resolvePlatformOrigin(args.runtime);
+    if (!platformOrigin)
+        return null;
+    const queueRes = await resolvePdfOcrQueue(args.runtime);
+    if (!queueRes.ok)
+        return null;
+    const queue = queueRes.value;
+    const storageCacheKey = args.cache.storageKey(args.cacheKey);
+    const jobId = await buildFoveatedPageJobId(storageCacheKey);
+    // Job data is persisted, so it carries no credential: the job resolves the
+    // internal service credential through its own runtime when it runs.
+    const jobInput = {
+        requestId: jobId,
+        userId: owner.userId,
+        sourceUrl: args.sourceUrl,
+        page: args.page,
+        pageWidthPx: Math.max(1, Math.floor(args.pageWidthPx)),
+        pageHeightPx: Math.max(1, Math.floor(args.pageHeightPx)),
+        ref: args.input.ref,
+        cacheKey: storageCacheKey,
+        renderProfile: args.renderProfile,
+        promptVersion: args.promptVersion,
+        aiOrigin: args.aiOrigin,
+        platformOrigin
+    };
+    if (owner.organizationId)
+        jobInput.organizationId = owner.organizationId;
+    // Admitted when this read resolved its source (`resolveFreshSourceUrl`).
+    if (args.input.ref.sourceRefreshUrl)
+        jobInput.sourceRefreshUrl = args.input.ref.sourceRefreshUrl;
+    if (args.input.ref.documentId)
+        jobInput.documentId = args.input.ref.documentId;
+    if (args.input.instructions)
+        jobInput.instructions = args.input.instructions;
+    if (args.input.visionFocusHint)
+        jobInput.visionFocusHint = args.input.visionFocusHint;
+    if (args.input.modelName)
+        jobInput.modelName = args.input.modelName;
+    const metadata = {
+        type: PDF_OCR_FOVEATE_PAGE_JOB_ID,
+        maxAttempts: 2,
+        billingUserId: owner.userId
+    };
+    if (owner.organizationId)
+        metadata.billingOrganizationId = owner.organizationId;
+    return queue.enqueue(jobInput, {
+        jobId,
+        jobName: PDF_OCR_FOVEATE_PAGE_JOB_ID,
+        attempts: 2,
+        metadata
+    });
+}
+/** Lowercased string value of the first matching field, or '' when absent. */
+function fieldStr(row, keys) {
+    const parsed = JsonObjectSchema.safeParse(row);
+    if (!parsed.success)
+        return '';
+    const rec = parsed.data;
+    for (const [k, v] of Object.entries(rec)) {
+        if (keys.includes(k.toLowerCase())) {
+            const str = z.string().safeParse(v);
+            if (str.success)
+                return str.data.trim().toLowerCase();
+            const num = z.number().safeParse(v);
+            if (num.success)
+                return String(num.data);
+        }
+    }
+    return '';
+}
+/** Best-effort title/tag of a row (schema-agnostic — tries common field names). */
+function rowTitle(row) {
+    return fieldStr(row, ['title', 'tag', 'label', 'name', 'mark', 'id', 'type']);
+}
+/** Best-effort dimension signature of a row (schema-agnostic). */
+function rowDims(row) {
+    const direct = fieldStr(row, ['dimensions', 'dims', 'size', 'dimension']);
+    if (direct)
+        return direct;
+    // Fall back to width×height×depth components when present.
+    const w = fieldStr(row, ['width', 'w']);
+    const h = fieldStr(row, ['height', 'h']);
+    const d = fieldStr(row, ['depth', 'd']);
+    const combined = [w, h, d].filter(Boolean).join('x');
+    return combined;
+}
+/**
+ * Merge per-cell rows for the foveated path.
+ *
+ * NEVER auto-dedups: two genuinely identical cabinets are valid, and silent
+ * dedup under-counts → an unsafe bid. Instead we keep ALL rows and emit a
+ * diagnostic that (a) records each row's cell provenance and (b) flags pairs of
+ * rows from ADJACENT/overlapping cells that share an identical title AND
+ * identical dimensions as a *possible* cross-cell duplicate (flag only).
+ */
+function mergeFoveatedRows(cellRows) {
+    const rows = cellRows.map((cr) => cr.row);
+    const provenance = cellRows.map((cr, index) => ({
+        index,
+        cell: `r${cr.cell.row}c${cr.cell.col}`
+    }));
+    const possibleDuplicates = [];
+    for (let i = 0; i < cellRows.length; i++) {
+        for (let j = i + 1; j < cellRows.length; j++) {
+            const A = cellRows[i];
+            const B = cellRows[j];
+            if (A.cell === B.cell)
+                continue; // same cell → not a seam duplicate
+            if (!cellsAreAdjacent(A.cell, B.cell))
+                continue;
+            const titleA = rowTitle(A.row);
+            const titleB = rowTitle(B.row);
+            const dimsA = rowDims(A.row);
+            const dimsB = rowDims(B.row);
+            if (titleA && titleA === titleB && dimsA && dimsA === dimsB) {
+                possibleDuplicates.push({ a: i, b: j, title: titleA, dims: dimsA });
+            }
+        }
+    }
+    return { rows, provenance, possibleDuplicates };
+}
+/**
+ * Foveated SCHEMA read: render the page as a grid of HIGH-DPI cells and extract
+ * each, merging rows with provenance + duplicate flags. Returns the merged rows,
+ * a diagnostics blob, and a short markdown note. Cost is bounded: the grid is
+ * capped at FOVEATE_MAX_CELLS cells, and the sweep aborts early if the first few
+ * cells all return zero rows (a blank/text page won't benefit from tiling).
+ */
+async function foveatedExtract(runtime, page, sourceUrl, pageWidthPx, pageHeightPx, input, renderer, aiOrigin, token) {
+    const grid = planFoveationGrid(pageWidthPx, pageHeightPx, FOVEATE_MAX_CELLS);
+    const cells = enumerateGridCells(grid, FOVEATE_DEFAULT_OVERLAP);
+    // schema present → structured EXTRACT per cell; absent → faithful TRANSCRIBE per
+    // cell (DESCRIBE mode). Describe keeps document.read a generic doc-intelligence tool:
+    // the vision model transcribes what's drawn (titles, dimension strings, callouts,
+    // detail tags) and the CALLER (e.g. the casework agent) interprets it — so a detail
+    // or section sheet with no titled "rows" still yields its dimensions instead of blank.
+    const wantsExtract = Boolean(input.schema);
+    const cellRows = [];
+    const cellTexts = [];
+    const perCellCounts = [];
+    const cellFailures = [];
+    // RENDER every cell from a SINGLE source fetch (a SharePoint pre-auth token is
+    // rejected — 401 — when fetched per cell / concurrently). The vision EXTRACT then
+    // runs per cell; extract POSTs the cell image to ai-web (no source fetch), so the
+    // extracts go CONCURRENTLY (batched, to not hammer the vision model) — each cell
+    // is ~15-25s and running them sequentially would blow the tool budget (the async
+    // rail timeout document.read exists to escape).
+    const rendered = await renderer.renderGridCells({ sourceUrl, page, cells });
+    const byKey = new Map(cells.map((c) => [`${c.row}:${c.col}`, c]));
+    const CONCURRENCY = 4;
+    const extractCell = async (rc) => {
+        const fallbackCell = {
+            col: rc.col,
+            row: rc.row,
+            cols: grid.cols,
+            rows: grid.rows,
+            overlap: FOVEATE_DEFAULT_OVERLAP
+        };
+        const cell = byKey.get(`${rc.row}:${rc.col}`) ?? fallbackCell;
+        return settle(async () => {
+            if (wantsExtract) {
+                const extractBody = {
+                    image: rc.pngBase64,
+                    schema: JsonObjectSchema.parse(input.schema),
+                    vocabulary: input.vocabulary,
+                    promptHint: input.instructions
+                };
+                if (input.rowContainerKeys)
+                    extractBody.rowContainerKeys = input.rowContainerKeys;
+                if (input.modelName)
+                    extractBody.modelName = input.modelName;
+                const extracted = await callExtract(runtime, aiOrigin, token, extractBody);
+                return {
+                    cell,
+                    rows: extracted.rows,
+                    text: extracted.raw
+                };
+            }
+            // DESCRIBE mode: transcribe this legible cell faithfully (no schema).
+            const ocrBody = {
+                image: rc.pngBase64,
+                prompt: foldOcrPrompt(input)
+            };
+            if (input.modelName)
+                ocrBody.modelName = input.modelName;
+            const ocr = await callOcr(runtime, aiOrigin, token, ocrBody);
+            return { cell, rows: [], text: ocr.markdown || ocr.text || '' };
+        });
+    };
+    let cellsRun = 0;
+    for (let i = 0; i < rendered.length; i += CONCURRENCY) {
+        const batch = rendered.slice(i, i + CONCURRENCY);
+        const results = await Promise.all(batch.map(extractCell));
+        for (let bIdx = 0; bIdx < batch.length; bIdx++) {
+            const res = results[bIdx];
+            const rc = batch[bIdx];
+            if (!res || !rc)
+                continue;
+            if (!res.ok) {
+                const err = 'Document cell extraction failed.';
+                cellFailures.push({ cell: `r${rc.row}c${rc.col}`, error: err });
+                continue;
+            }
+            const { cell, rows, text } = res.value;
+            cellsRun += 1;
+            perCellCounts.push({ cell: `r${cell.row}c${cell.col}`, rows: rows.length });
+            for (const row of rows)
+                cellRows.push({ row, cell });
+            if (text && text.trim())
+                cellTexts.push({ cell, text: text.trim() });
+        }
+    }
+    if (cellFailures.length === rendered.length && rendered.length > 0) {
+        throw new Error(`foveated read failed in every cell (${cellFailures.length}/${rendered.length})`);
+    }
+    const merged = mergeFoveatedRows(cellRows);
+    const diagnostics = {
+        foveated: true,
+        grid: { cols: grid.cols, rows: grid.rows },
+        cellsPlanned: cells.length,
+        cellsRun,
+        perCellRowCounts: perCellCounts,
+        provenance: merged.provenance
+    };
+    if (cellFailures.length > 0)
+        diagnostics.cellFailures = cellFailures;
+    if (merged.possibleDuplicates.length > 0) {
+        diagnostics.possibleCrossCellDuplicates = merged.possibleDuplicates;
+    }
+    // DESCRIBE mode → the markdown IS the deliverable: a spatially-labelled transcription
+    // of the whole sheet (top→bottom, left→right) the caller reads + interprets. EXTRACT
+    // mode → a short provenance summary (the rows are the deliverable).
+    const markdown = wantsExtract
+        ? `foveated ${cellsRun}-cell read (${grid.cols}×${grid.rows} grid, ${merged.rows.length} rows${merged.possibleDuplicates.length > 0
+            ? `, ${merged.possibleDuplicates.length} possible cross-cell duplicate(s) flagged`
+            : ''})`
+        : cellTexts
+            .slice()
+            .sort((a, b) => a.cell.row - b.cell.row || a.cell.col - b.cell.col)
+            .map(({ cell, text }) => `### sheet region — row ${cell.row + 1}/${grid.rows}, col ${cell.col + 1}/${grid.cols}\n${text}`)
+            .join('\n\n') || '(no legible text found on this sheet)';
+    return { rows: merged.rows, diagnostics, markdown };
+}
+async function tryFoveatedExtract(runtime, page, sourceUrl, pageWidthPx, pageHeightPx, input, renderer, aiOrigin, token) {
+    return settle(() => foveatedExtract(runtime, page, sourceUrl, pageWidthPx, pageHeightPx, input, renderer, aiOrigin, token));
+}
+async function tryWriteCache(cache, record) {
+    return settle(async () => {
+        await writeCache(cache, record);
+    });
+}
+async function processPage(page, input, renderer, aiOrigin, token, cache, runtime, ctx) {
+    const renderProfile = DEFAULT_RENDER_PROFILE;
+    const promptVersion = input.promptVersion ?? DEFAULT_PROMPT_VERSION;
+    const cacheKey = buildCacheKey(input.ref, page, renderProfile, promptVersion);
+    const wantsExtract = Boolean(input.schema);
+    // 1. Cache lookup. A cached record satisfies the markdown path always; it
+    //    satisfies the extract path too only when it already carries extractRows.
+    const cached = await lookupCache(cache, cacheKey, runtime);
+    if (cached && isProcessingCacheRecord(cached)) {
+        if (!isStaleProcessingCacheRecord(cached)) {
+            return { page: processingPage(page, cacheKey, readString(cached.quality?.jobId)) };
+        }
+    }
+    if (cached && isErrorCacheRecord(cached)) {
+        // Not terminal: after the cool-off a re-read falls THROUGH to a fresh
+        // render + re-enqueue (fresh source URL), which overwrites this marker
+        // with a processing one. Within the cool-off, serve the error so a tight
+        // agent loop cannot hot-requeue the same failing page.
+        if (!isRetryableErrorCacheRecord(cached)) {
+            return { page: errorPage(page, cacheKey, cached) };
+        }
+    }
+    else if (cached && (!wantsExtract || cached.extractRows !== undefined)) {
+        const cachedResult = {
+            page: { index: page, text: cached.ocrMarkdown, cacheHit: true, status: 'ready', cacheKey }
+        };
+        if (wantsExtract) {
+            cachedResult.rows = cached.extractRows ?? [];
+        }
+        return cachedResult;
+    }
+    // 2. Render the page PNG ONCE — fed to both the OCR and (optional) extract call.
+    const sourceUrl = await resolveFreshSourceUrl(runtime, input.ref, `document-read:p${page}:${cacheKey}`);
+    const rendered = await renderer.renderPageClip({ sourceUrl, page, dpi: 150 });
+    // 3+4. ONE vision call per page. Each vision call on a rendered sheet is the
+    //    dominant cost (tens of seconds); doing BOTH an OCR pass AND a schema
+    //    extract on the same image doubled the latency and pushed a structured read
+    //    past the tool budget for no added value — the extract reads the SAME image
+    //    and its raw text serves as the page markdown. So:
+    //      - schema read  → extract ONLY (rows + raw text as markdown)
+    //      - markdown read → OCR ONLY
+    let ocrMarkdown = '';
+    let ocrModelId;
+    let extractRows;
+    let diagnostics;
+    let quality;
+    // A large/dense architectural sheet downscaled to ONE full-page image makes small
+    // detail text illegible → a full-page read returns near-nothing for ~20s of wasted
+    // vision time. So for a LARGE (downscale-capped) page we FOVEATE: render a few HIGH-DPI
+    // cells from one source fetch and read each — with a schema → EXTRACT rows per cell;
+    // without → DESCRIBE (transcribe) each cell. Foveation now runs for BOTH modes so the
+    // describe-then-interpret path reads big sheets legibly, not only schema reads. A SMALL
+    // page is read in a single full-page pass (no tiling needed).
+    const longestEdge = Math.max(rendered.width ?? 0, rendered.height ?? 0);
+    let foveated = null;
+    if (longestEdge >= FOVEATE_MIN_LONGEST_EDGE_PX) {
+        if (asyncFoveationEnabled(runtime, input)) {
+            const jobId = await enqueueFoveatedPage({
+                runtime,
+                ctx,
+                input,
+                page,
+                sourceUrl,
+                pageWidthPx: rendered.width ?? 0,
+                pageHeightPx: rendered.height ?? 0,
+                cacheKey,
+                cache,
+                renderProfile,
+                promptVersion,
+                aiOrigin
+            });
+            if (jobId) {
+                const markerRes = await tryWriteProcessingMarker({
+                    cache,
+                    input,
+                    page,
+                    cacheKey,
+                    renderProfile,
+                    promptVersion,
+                    jobId
+                });
+                if (!markerRes.ok) {
+                    // Declared-optional: the queued job writes the final cache record.
+                    const diagnostic = settleNow(() => getLogger('documents.read', runtime).warn('processing marker write failed', {
+                        cacheKey,
+                        error: valueFreeFailure(markerRes.cause)
+                    }));
+                    if (!diagnostic.ok)
+                        settleNow(() => runtime.diagnostics.error('Document diagnostic failed', { scope: 'docs', plugin: 'documents.read', error: new AggregateError([markerRes.cause, diagnostic.cause], 'Primary failure and diagnostic failed.', { cause: markerRes.cause }) }));
+                }
+                return {
+                    page: processingPage(page, cacheKey, jobId),
+                    diagnostics: {
+                        asyncStatus: 'processing',
+                        cacheKey,
+                        jobId,
+                        message: ASYNC_PROCESSING_MESSAGE
+                    }
+                };
+            }
+        }
+        const foveatedRes = await tryFoveatedExtract(runtime, page, sourceUrl, rendered.width ?? 0, rendered.height ?? 0, input, renderer, aiOrigin, token);
+        if (foveatedRes.ok) {
+            foveated = foveatedRes.value;
+        }
+        else {
+            foveated = null;
+            diagnostics = {
+                foveationError: valueFreeFailure(foveatedRes.cause)
+            };
+        }
+    }
+    if (foveated) {
+        if (wantsExtract)
+            extractRows = foveated.rows;
+        diagnostics = foveated.diagnostics;
+        ocrMarkdown = foveated.markdown;
+        quality = foveated.diagnostics;
+    }
+    else if (wantsExtract) {
+        // Small page, OR foveation didn't run/failed → one full-page extract.
+        const extractBody = {
+            image: rendered.pngBase64,
+            schema: JsonObjectSchema.parse(input.schema),
+            promptHint: input.instructions
+        };
+        if (input.vocabulary)
+            extractBody.vocabulary = input.vocabulary;
+        if (input.rowContainerKeys)
+            extractBody.rowContainerKeys = input.rowContainerKeys;
+        if (input.modelName)
+            extractBody.modelName = input.modelName;
+        const extracted = await callExtract(runtime, aiOrigin, token, extractBody);
+        extractRows = extracted.rows;
+        const nextDiagnostics = {};
+        if (diagnostics)
+            Object.assign(nextDiagnostics, diagnostics);
+        Object.assign(nextDiagnostics, extracted.diagnostics);
+        diagnostics = nextDiagnostics;
+        ocrMarkdown = extracted.raw ?? '';
+        quality = extracted.diagnostics;
+    }
+    else {
+        // Small page (or foveation failed), DESCRIBE mode → a single VISION OCR pass.
+        const ocrBody = {
+            image: rendered.pngBase64,
+            prompt: foldOcrPrompt(input)
+        };
+        if (input.modelName)
+            ocrBody.modelName = input.modelName;
+        const ocr = await callOcr(runtime, aiOrigin, token, ocrBody);
+        ocrMarkdown = ocr.markdown || ocr.text;
+        ocrModelId = readString(ocr.metadata?.modelId);
+        quality = ocr.metadata;
+    }
+    // 5. Write to cache (markdown always; extractRows when computed).
+    // Simple hash: length of pngBase64 + first 32 chars (deterministic, lightweight)
+    const sourceHash = `${rendered.pngBase64.length}:${rendered.pngBase64.slice(0, 32)}`;
+    const cacheRecord = {
+        id: cacheKey,
+        ref: input.ref,
+        page,
+        renderProfile,
+        promptVersion,
+        ocrMarkdown,
+        quality,
+        sourceHash,
+        renderedAt: new Date().toISOString()
+    };
+    if (extractRows !== undefined)
+        cacheRecord.extractRows = extractRows;
+    if (ocrModelId)
+        cacheRecord.ocrModelId = ocrModelId;
+    // Best-effort cache write — a persistence failure (cloud-api adapter not in
+    // scope, platform-web /api/documents/page-cache down) must NOT discard the
+    // freshly-computed OCR/extract result the caller needs. Next read re-renders.
+    const writeRes = await tryWriteCache(cache, cacheRecord);
+    if (!writeRes.ok) {
+        // Declared-optional: the page result is returned regardless.
+        const diagnostic = settleNow(() => getLogger('documents.read', runtime).warn('page-cache write failed; result returned uncached', {
+            cacheKey,
+            error: valueFreeFailure(writeRes.cause)
+        }));
+        if (!diagnostic.ok)
+            settleNow(() => runtime.diagnostics.error('Document diagnostic failed', { scope: 'docs', plugin: 'documents.read', error: new AggregateError([writeRes.cause, diagnostic.cause], 'Primary failure and diagnostic failed.', { cause: writeRes.cause }) }));
+    }
+    const pageReadResult = {
+        page: { index: page, text: ocrMarkdown, cacheHit: false, status: 'ready', cacheKey }
+    };
+    if (wantsExtract)
+        pageReadResult.rows = extractRows ?? [];
+    if (diagnostics)
+        pageReadResult.diagnostics = diagnostics;
+    return pageReadResult;
+}
+/**
+ * Render a text-layer sheet index as agent-facing markdown — the document STRUCTURE
+ * (page → sheet number → title), domain-neutral. Which sheets matter for a given takeoff is
+ * the model's call, steered by the consuming surface's prompt; this index deliberately does
+ * NOT pre-filter or label a trade (e.g. "casework") so the same tool serves any discipline.
+ */
+function formatOutlineMarkdown(outline) {
+    const sizeNote = outline.pageWidthIn && outline.pageHeightIn
+        ? `${outline.pageWidthIn}×${outline.pageHeightIn}" sheets`
+        : 'sheets';
+    const entry = (s) => `- p${s.page}${s.number ? ` — ${s.number}` : ''}${s.title ? ` — ${s.title}` : ''}`;
+    const lines = [`# Sheet index — ${outline.pageCount} pages, ${sizeNote}`, ''];
+    // When the text layer is garbled (a custom CAD font encoding pdftotext can't decode — real
+    // on some architects' sets) the titles are junk: tell the agent to classify by VISION.
+    if (outline.textLayerReliable === false) {
+        const garbledPages = outline.sheets.filter((s) => s.garbled).map((s) => s.page);
+        lines.push('## ⚠️ Text layer unreliable — classify sheets by VISION, not these titles', `This drawing set has a garbled/unreadable text layer (a custom font encoding), so the sheet ` +
+            `titles below are NOT trustworthy${garbledPages.length ? ` (affected pages: ${garbledPages.join(', ')})` : ''}. Open the candidate sheets directly with document.view / document.read to SEE and ` +
+            'classify each one, rather than trusting this index.', '');
+    }
+    lines.push('## Sheets (page — number — title):');
+    for (const s of outline.sheets)
+        lines.push(entry(s));
+    return lines.join('\n');
+}
+function tryResolveExtractionSchemaDescriptor(runtime, schemaId) {
+    return settleNow(() => runtime
+        .query('ai/extraction-schema')
+        .withId(schemaId)
+        .firstDescriptor());
+}
+async function safeFetchOutline(renderer, sourceUrl) {
+    return settle(() => renderer.outline({ sourceUrl }));
+}
+// ---------------------------------------------------------------------------
+// ToolImplementation
+// ---------------------------------------------------------------------------
+export class DocumentReadImplementation {
+    /** Builds the renderer for each call's runtime (the plugin selects it by scope). */
+    rendererFor;
+    constructor(rendererFor) {
+        this.rendererFor = rendererFor;
+    }
+    async execute(rawInput, runtime, ctx) {
+        const renderer = this.rendererFor(runtime);
+        const parsed = DocumentReadInputSchema.parse(rawInput);
+        // Resolve schemaId → inline schema when `schema` is absent.
+        // Inline `schema` always takes precedence over `schemaId`.
+        // The descriptor ALSO carries an optional domain prompt preamble + vocabulary
+        // (PLAN F1): a casework cabinet schema delivers its drawing-literacy estimator
+        // prompt as DATA so the GENERIC kernel stays domain-agnostic. We fold those into
+        // `input.instructions` / `input.vocabulary` so they ride callExtract → the
+        // /api/internal/document-extract `promptHint` / `vocabulary` → extractStructured.
+        let resolvedSchema = parsed.schema;
+        let schemaPreamble;
+        let schemaVocabulary;
+        let schemaRowContainerKeys;
+        let schemaModelName;
+        if (!resolvedSchema && parsed.schemaId) {
+            const schemaRes = tryResolveExtractionSchemaDescriptor(runtime, parsed.schemaId);
+            if (schemaRes.ok) {
+                const descriptor = schemaRes.value;
+                if (descriptor?.jsonSchema) {
+                    resolvedSchema = descriptor.jsonSchema;
+                    if (descriptor.promptPreamble)
+                        schemaPreamble = descriptor.promptPreamble;
+                    if (descriptor.vocabulary)
+                        schemaVocabulary = descriptor.vocabulary;
+                    if (descriptor.rowContainerKeys)
+                        schemaRowContainerKeys = descriptor.rowContainerKeys;
+                    if (descriptor.preferredModelName)
+                        schemaModelName = descriptor.preferredModelName;
+                }
+            }
+            else {
+                const diagnostic = settleNow(() => getLogger('documents.read', runtime).warn('extraction schema descriptor lookup failed; reading as markdown', {
+                    schemaId: parsed.schemaId,
+                    error: valueFreeFailure(schemaRes.cause)
+                }));
+                if (!diagnostic.ok)
+                    settleNow(() => runtime.diagnostics.error('Document diagnostic failed', { scope: 'docs', plugin: 'documents.read', error: new AggregateError([schemaRes.cause, diagnostic.cause], 'Primary failure and diagnostic failed.', { cause: schemaRes.cause }) }));
+            }
+        }
+        // Rebuild input with the resolved schema (+ domain preamble/vocabulary) so
+        // processPage / execute below see a consistent DocumentReadInput. The descriptor
+        // preamble leads; any caller-supplied instructions follow it. Caller-supplied
+        // vocabulary takes precedence over the descriptor default.
+        const foldedInstructions = [schemaPreamble, parsed.instructions].filter(Boolean).join('\n\n') || undefined;
+        // Caller-supplied modelName wins; otherwise the descriptor declares the model.
+        const resolvedModelName = parsed.modelName ?? schemaModelName;
+        const needsRebuild = resolvedSchema !== parsed.schema ||
+            foldedInstructions !== parsed.instructions ||
+            (schemaVocabulary !== undefined && parsed.vocabulary === undefined) ||
+            (schemaRowContainerKeys !== undefined && parsed.rowContainerKeys === undefined) ||
+            (resolvedModelName !== undefined && parsed.modelName === undefined);
+        let input = parsed;
+        if (needsRebuild) {
+            input = { ...parsed, schema: resolvedSchema };
+            if (foldedInstructions !== undefined)
+                input.instructions = foldedInstructions;
+            if (parsed.vocabulary === undefined && schemaVocabulary !== undefined) {
+                input.vocabulary = schemaVocabulary;
+            }
+            if (parsed.rowContainerKeys === undefined && schemaRowContainerKeys !== undefined) {
+                input.rowContainerKeys = schemaRowContainerKeys;
+            }
+            if (parsed.modelName === undefined && resolvedModelName !== undefined) {
+                input.modelName = resolvedModelName;
+            }
+        }
+        // The ai-web origin that hosts the internal OCR + extract endpoints: the
+        // declared `ai` service (NOT_FOUND when this host declares none).
+        const aiOrigin = await resolveAiInternalOrigin(runtime);
+        const token = await resolveInternalServiceToken(runtime);
+        const cache = await resolvePageCacheClient(runtime, ctx, token);
+        // Determine pages to read
+        const pagesToRead = input.pages ?? [];
+        if (pagesToRead.length === 0) {
+            // No pages specified — return the document STRUCTURE so the agent can
+            // target the right pages. Prefer the FREE text-layer sheet index (pdfinfo +
+            // pdftotext, no vision, ~instant): it lists every sheet's number/title and
+            // flags the casework sheets. Fall back to a vision OCR of page 1 only when
+            // the PDF has no text layer (a scanned set).
+            const sourceUrl = await resolveFreshSourceUrl(runtime, input.ref, 'document-read:outline');
+            const outlineRes = await safeFetchOutline(renderer, sourceUrl);
+            if (outlineRes.ok) {
+                if (outlineRes.value.sheets.length > 0) {
+                    return {
+                        kind: 'markdown',
+                        pages: [
+                            {
+                                index: 0,
+                                text: formatOutlineMarkdown(outlineRes.value),
+                                cacheHit: false,
+                                title: 'Sheet index'
+                            }
+                        ]
+                    };
+                }
+            }
+            else {
+                const diagnostic = settleNow(() => getLogger('documents.read', runtime).warn('document outline unavailable; using vision overview', {
+                    error: valueFreeFailure(outlineRes.cause)
+                }));
+                if (!diagnostic.ok)
+                    settleNow(() => runtime.diagnostics.error('Document diagnostic failed', { scope: 'docs', plugin: 'documents.read', error: new AggregateError([outlineRes.cause, diagnostic.cause], 'Primary failure and diagnostic failed.', { cause: outlineRes.cause }) }));
+            }
+            const overview = await renderer.renderOverview({ sourceUrl, dpi: 72 });
+            const ocrResult = await callOcr(runtime, aiOrigin, token, {
+                image: overview.pngBase64,
+                prompt: foldOcrPrompt({
+                    visionFocusHint: input.visionFocusHint ?? 'overview',
+                    instructions: input.instructions ??
+                        'Extract the table of contents, sheet list, or document structure.'
+                })
+            });
+            return {
+                kind: 'markdown',
+                pages: [
+                    {
+                        index: 0,
+                        title: 'Overview / TOC',
+                        text: ocrResult.markdown || ocrResult.text,
+                        cacheHit: false
+                    }
+                ]
+            };
+        }
+        // Read requested pages (in parallel, capped at 10 concurrent).
+        const CONCURRENCY = 10;
+        const pageReads = [];
+        for (let i = 0; i < pagesToRead.length; i += CONCURRENCY) {
+            const batch = pagesToRead.slice(i, i + CONCURRENCY);
+            const settled = await Promise.all(batch.map((page) => processPage(page, input, renderer, aiOrigin, token, cache, runtime, ctx)));
+            pageReads.push(...settled);
+        }
+        // Sort by page index
+        pageReads.sort((a, b) => a.page.index - b.page.index);
+        // Structured path: a schema produces aggregated rows across all pages.
+        // (Each page was extracted from its own rendered PNG inside processPage.)
+        if (input.schema) {
+            const rows = [];
+            const perPageDiagnostics = {};
+            for (const read of pageReads) {
+                if (read.rows)
+                    rows.push(...read.rows);
+                if (read.diagnostics) {
+                    perPageDiagnostics[`page-${read.page.index}`] = read.diagnostics;
+                }
+            }
+            // Completeness gate (EMPIRICAL-VERIFIED.md §completeness gate): a STRUCTURED
+            // (schema) read that yields ZERO rows from the requested pages is an UNDER-READ,
+            // not an empty document. Surface it as a diagnostic so the caller never persists
+            // a casework-flagged sheet as "takeoff-ready, no cabinets" — a silent dropped /
+            // under-bid. The agent should re-read at higher DPI / a tighter crop, or report
+            // the sheet unreadable, rather than treat zero rows as authoritative.
+            if (rows.length === 0) {
+                perPageDiagnostics.completeness = {
+                    status: 'under_read',
+                    message: 'Structured read returned zero rows from the requested page(s) — likely an under-read ' +
+                        '(illegible render or a vision miss), not a sheet with no casework. Re-read at a higher ' +
+                        'DPI / tighter crop, or report the sheet as unreadable; do NOT treat zero rows as authoritative.'
+                };
+            }
+            const structuredResult = {
+                kind: 'structured',
+                rows
+            };
+            if (Object.keys(perPageDiagnostics).length > 0) {
+                structuredResult.diagnostics = perPageDiagnostics;
+            }
+            return structuredResult;
+        }
+        // Markdown path: no schema. When input.question is set, the calling agent
+        // reads the returned page markdown to answer it — there is no
+        // markdown-analyzer endpoint, so question alone does NOT trigger extract.
+        return { kind: 'markdown', pages: pageReads.map((r) => r.page) };
+    }
+}
+export function createDocumentReadTool(rendererFor) {
+    return new DocumentReadImplementation(rendererFor);
+}
+//# sourceMappingURL=document-read.impl.js.map