@hraness/wordcell 0.26.3 → 0.27.0

package/src/pdf/layout.ts

@@ -36,6 +36,7 @@ export type ParsedPopplerXml = {
 };
 
 export type PdfLayoutBlock =
+  | { readonly kind: "table"; readonly page: number; readonly rows: readonly (readonly string[])[] }
   | {
       readonly kind: "heading";
       readonly page: number;
@@ -456,7 +457,7 @@ export function layoutBlocks(pages: readonly PdfPageLayout[]): readonly PdfLayou
 
   for (const page of pages) {
     const lines = (linesByPage.get(page.page) ?? []).filter(
-      (line) => !repeatedMargins.has(normalizedMarginText(line.text)),
+      (line) => !(line.top <= page.height * 0.06 || line.top + line.height >= page.height * 0.94) || !repeatedMargins.has(normalizedMarginText(line.text)),
     );
     const steps = lines.slice(1).map((line, index) =>
       Math.max(0, line.top - (lines[index]?.top ?? line.top)));
@@ -491,7 +492,7 @@ export function layoutBlocks(pages: readonly PdfPageLayout[]): readonly PdfLayou
       const { line, index } = event;
       const previous = lines[index - 1];
       const gapBefore = previous === undefined ? Number.POSITIVE_INFINITY : line.top - previous.top;
-      const fontHeading = line.fontSize > bodySize * 1.08;
+      const fontHeading = line.fontSize > bodySize * 1.08 && !/[=∫∑√⁰¹²³⁴⁵⁶⁷⁸⁹]/u.test(line.text);
       const boldHeading = line.boldRatio >= 0.78
         && line.text.length <= 180
         && gapBefore >= normalStep * 1.45;
@@ -516,7 +517,7 @@ export function layoutBlocks(pages: readonly PdfPageLayout[]): readonly PdfLayou
     }
     flushParagraph();
   }
-  return output.filter((block) => block.kind === "image" || block.text.trim() !== "");
+  return output.filter((block) => block.kind === "image" || block.kind === "table" || block.text.trim() !== "");
 }
 
 export function parsePdfImageInterpretations(value: unknown): readonly PdfImageInterpretation[] {
@@ -616,3 +617,135 @@ export function parsePdfImageInterpretations(value: unknown): readonly PdfImageI
   }
   return output;
 }
+
+/** Geometry evidence is deliberately conservative: uncertain structure remains visible in quality. */
+export function analyzePdfLayout(pages: readonly PdfPageLayout[]): { readonly blocks: readonly PdfLayoutBlock[]; readonly issues: readonly import("./model.js").PdfQualityIssue[] } {
+  const issues: import("./model.js").PdfQualityIssue[] = [];
+  const blocks: PdfLayoutBlock[] = [];
+  const marginLines = new Map(pages.filter(page => page.text.length <= 4000).map(page => [page.page, pageLines(page)]));
+  const margins = repeatedMarginLines(pages, marginLines);
+  for (const originalInput of pages) {
+    const original = { ...originalInput, text: originalInput.text.filter(fragment => !(fragment.top <= originalInput.height * 0.06 || fragment.top + fragment.height >= originalInput.height * 0.94) || !margins.has(normalizedMarginText(fragment.text))) };
+    const warn = (code: import("./model.js").PdfQualityIssue["code"]): void => {
+      if (!issues.some(issue => issue.page === original.page && issue.code === code)) issues.push({ page: original.page, code });
+    };
+    // Bound quadratic geometry analysis independently of the parser's byte limit.
+    if (original.text.length > 4000) {
+      warn("reading-order-uncertain"); blocks.push(...layoutBlocks([original])); continue;
+    }
+    if (original.text.some(fragment => /[∫∑√]/u.test(fragment.text))) warn("math-structure-uncertain");
+    const text = [...original.text].sort((a, b) => a.top - b.top || a.left - b.left);
+    const consumed = new Set<PdfTextFragment>();
+    const replacements = new Map<PdfTextFragment, PdfTextFragment>();
+    const superscripts: Record<string, string> = { "0": "⁰", "1": "¹", "2": "²", "3": "³", "4": "⁴", "5": "⁵", "6": "⁶", "7": "⁷", "8": "⁸", "9": "⁹", "+": "⁺", "-": "⁻", "=": "⁼", "(": "⁽", ")": "⁾", "n": "ⁿ", "i": "ⁱ" };
+    for (const small of text) {
+      const bases = text.filter(base => base !== small && base.fontSize >= small.fontSize * 1.3
+        && small.top < base.top && small.top + small.height > base.top - base.height * 0.25
+        && Math.abs(small.left - (base.left + base.width)) < base.fontSize * 0.6);
+      if (bases.length === 0) continue;
+      const base = bases[0]!;
+      const glyphs = [...small.text.trim()];
+      if (bases.length === 1 && glyphs.length > 0 && glyphs.length <= 8 && glyphs.every(glyph => superscripts[glyph] !== undefined) && !replacements.has(base)) {
+        replacements.set(base, { ...base, text: base.text + glyphs.map(glyph => superscripts[glyph]).join(""), width: small.left + small.width - base.left });
+        consumed.add(small);
+      } else warn("math-structure-uncertain");
+    }
+    const fragments = text.filter(fragment => !consumed.has(fragment)).map(fragment => replacements.get(fragment) ?? fragment);
+    const page: PdfPageLayout = { ...original, text: fragments };
+    const rows: PdfTextFragment[][] = [];
+    for (const fragment of fragments) {
+      const row = rows.at(-1);
+      if (row === undefined || Math.abs(fragment.top - row[0]!.top) > Math.max(2, fragment.height * 0.2)) rows.push([fragment]);
+      else row.push(fragment);
+    }
+    const cellRows = rows.map(row => {
+      const groups: PdfTextFragment[][] = [];
+      for (const fragment of [...row].sort((a, b) => a.left - b.left)) {
+        const prior = groups.at(-1), last = prior?.at(-1);
+        if (last === undefined || fragment.left - (last.left + last.width) > Math.max(12, fragment.fontSize * 1.5)) groups.push([fragment]);
+        else prior!.push(fragment);
+      }
+      return groups;
+    });
+    const tables: Array<{ top: number; bottom: number; block: PdfLayoutBlock; fragments: PdfTextFragment[] }> = [];
+    for (let index = 0; index < cellRows.length; index++) {
+      const first = cellRows[index]!;
+      if (first.length < 2 || first.length > 12) continue;
+      const group = [first];
+      let next = index + 1;
+      for (; next < cellRows.length; next++) {
+        const candidate = cellRows[next]!;
+        if (candidate.length !== first.length || candidate.some((cell, column) => Math.abs(cell[0]!.left - first[column]![0]!.left) > 4)) break;
+        if (candidate[0]![0]!.top - group.at(-1)![0]![0]!.top > Math.max(40, candidate[0]![0]!.height * 3)) break;
+        group.push(candidate);
+      }
+      const cells = group.map(row => row.map(cell => joinFragments(cell)));
+      const header = first.every(cell => cell.every(fragment => fragment.bold));
+      const numeric = cells.slice(1).some(row => row.slice(1).some(cell => /^[-+\d$€£]/u.test(cell.trim())));
+      const compact = cells.every(row => row.every(cell => cell.length <= 100));
+      if (group.length >= 3 && compact && header && numeric) {
+        const members = group.flat(2);
+        tables.push({ top: Math.min(...members.map(fragment => fragment.top)), bottom: Math.max(...members.map(fragment => fragment.top + fragment.height)), block: { kind: "table", page: page.page, rows: cells }, fragments: members });
+        index = next - 1;
+      } else if (group.length >= 3 && first.length >= 3) warn("table-structure-uncertain");
+    }
+    const tableFragments = new Set(tables.flatMap(table => table.fragments));
+    const remaining = fragments.filter(fragment => !tableFragments.has(fragment));
+    const emitBand = (band: readonly PdfTextFragment[], images: readonly PdfImageCandidate[]): void => {
+      if (band.length === 0 && images.length === 0) return;
+      // Repeated gutters are detected before line grouping can join adjacent columns.
+      const candidates = new Set<number>();
+      for (const row of cellRows) {
+        for (let i = 1; i < row.length; i++) {
+          const left = row[i - 1]!.at(-1)!, right = row[i]![0]!;
+          const gap = right.left - (left.left + left.width);
+          if (gap >= Math.max(page.width * 0.025, left.fontSize * 1.5)) candidates.add(Math.round((left.left + left.width + right.left) / 2));
+        }
+      }
+      const valid = [...candidates].filter(gutter => {
+        const left = band.filter(fragment => fragment.left + fragment.width <= gutter);
+        const right = band.filter(fragment => fragment.left >= gutter);
+        if (left.length + right.length !== band.length || left.length < 3 || right.length < 3) return false;
+        if (left.filter(fragment => fragment.width > page.width * 0.18).length < 2 || right.filter(fragment => fragment.width > page.width * 0.18).length < 2) return false;
+        const overlap = Math.min(Math.max(...left.map(fragment => fragment.top)), Math.max(...right.map(fragment => fragment.top))) - Math.max(Math.min(...left.map(fragment => fragment.top)), Math.min(...right.map(fragment => fragment.top)));
+        return overlap > Math.max(...band.map(fragment => fragment.height)) * 1.5;
+      });
+      if (valid.length > 0) {
+        const gutter = valid[Math.floor(valid.length / 2)]!;
+        if (images.some(image => image.left < gutter && image.left + image.width > gutter)) {
+          warn("reading-order-uncertain"); blocks.push(...layoutBlocks([{ ...page, text: band, images }])); return;
+        }
+        for (const left of [true, false]) blocks.push(...layoutBlocks([{ ...page, text: band.filter(fragment => left ? fragment.left + fragment.width <= gutter : fragment.left >= gutter), images: images.filter(image => left ? image.left + image.width <= gutter : image.left >= gutter) }]));
+      } else {
+        if (band.length >= 6 && cellRows.filter(row => row.length >= 2 && row.some(cell => band.includes(cell[0]!))).length >= 3) warn("reading-order-uncertain");
+        blocks.push(...layoutBlocks([{ ...page, text: band, images }]));
+      }
+    };
+    // Spanning headings split vertical regions; tables retain their exact place.
+    const bodyFont = weightedBodyFontSize(pageLines(page));
+    const gutterVotes = new Map<number, number>();
+    for (const row of cellRows) for (let i = 1; i < row.length; i++) {
+      const left = row[i - 1]!.at(-1)!, right = row[i]![0]!;
+      if (right.left - (left.left + left.width) < Math.max(12, left.fontSize * 1.5)) continue;
+      const gutter = Math.round((left.left + left.width + right.left) / 20) * 10;
+      gutterVotes.set(gutter, (gutterVotes.get(gutter) ?? 0) + 1);
+    }
+    const repeatedGutters = [...gutterVotes].filter(([, votes]) => votes >= 3).map(([gutter]) => gutter);
+    const spans = remaining.filter(fragment => fragment.width > page.width * 0.65 || (fragment.fontSize > bodyFont * 1.08 && repeatedGutters.some(gutter => fragment.left < gutter && fragment.left + fragment.width > gutter)));
+    const boundaries = [...tables.map(table => ({ top: table.top, bottom: table.bottom, table, span: null as PdfTextFragment | null })), ...spans.map(span => ({ top: span.top, bottom: span.top + span.height, table: null, span }))].sort((a, b) => a.top - b.top);
+    const emitted = new Set<PdfTextFragment>(), emittedImages = new Set<PdfImageCandidate>();
+    for (const boundary of boundaries) {
+      const band = remaining.filter(fragment => !emitted.has(fragment) && fragment !== boundary.span && fragment.top < boundary.top);
+      const images = page.images.filter(image => !emittedImages.has(image) && image.top < boundary.top);
+      emitBand(band, images); for (const fragment of band) emitted.add(fragment); for (const image of images) emittedImages.add(image);
+      if (boundary.table !== null) blocks.push(boundary.table.block);
+      if (boundary.span !== null) {
+        const span = boundary.span;
+        blocks.push(span.fontSize > bodyFont * 1.08 ? { kind: "heading", page: page.page, level: 2, text: span.text } : { kind: "paragraph", page: page.page, text: span.text });
+        emitted.add(span);
+      }
+    }
+    emitBand(remaining.filter(fragment => !emitted.has(fragment)), page.images.filter(image => !emittedImages.has(image)));
+  }
+  return { blocks, issues };
+}

package/src/pdf/markdown.ts

@@ -24,7 +24,7 @@ export type ResolvedPdfImage = {
 function escapeInline(value: string): string {
   return sanitizeTerminalText(value)
     .replace(/\\/gu, "\\\\")
-    .replace(/([`*_[\]{}<>#])/gu, "\\$1")
+    .replace(/([`*_[\]{}<>#|])/gu, "\\$1")
     .replace(/\s+/gu, " ")
     .trim();
 }
@@ -81,6 +81,12 @@ function markdownContent(
       lines.push(imageMarkdown(resolved), "");
       continue;
     }
+    if (block.kind === "table") {
+      textBlockCount += 1;
+      const rows = block.rows.map(row => `| ${row.map(cell => escapeInline(cell)).join(" | ")} |`);
+      if (rows.length > 0) lines.push(rows[0]!, `| ${block.rows[0]!.map(() => "---").join(" | ")} |`, ...rows.slice(1), "");
+      continue;
+    }
     if (block.kind === "heading") {
       headingCount += 1;
       lines.push(`${"#".repeat(Math.max(2, Math.min(6, block.level)))} ${escapeInline(block.text)}`, "");

package/src/pdf/model.ts

@@ -126,7 +126,14 @@ export type PdfManifestImage = PdfBounds & {
   readonly metadata: PdfImageSemanticMetadata | null;
 };
 
+export type PdfQualityIssue = {
+  readonly code: "reading-order-uncertain" | "table-structure-uncertain" | "math-structure-uncertain" | "ocr-needed";
+  readonly page: number;
+};
+
 export type PdfCaptureManifest = {
+  readonly markdown?: { readonly path: string; readonly bytes: number; readonly sha256: string };
+  readonly quality?: { readonly schemaVersion: 1; readonly issues: readonly PdfQualityIssue[] };
   readonly schemaVersion: typeof PDF_CAPTURE_MANIFEST_SCHEMA_VERSION;
   readonly kind: "pdf";
   readonly capturedAt: string;
@@ -204,6 +211,8 @@ export type PdfCaptureOutcome = {
 };
 
 export type PdfToolCommand = {
+  /** An external supervisor may own the inherited group and its final cleanup. */
+  readonly processGroup?: "new" | "inherit";
   readonly command: readonly string[];
   readonly timeoutMs: number;
   readonly maxOutputBytes: number;

package/src/pdf/persist.ts

@@ -212,9 +212,15 @@ export function persistPdfCapture(input: PersistPdfCaptureInput): string {
       chmodSync(destination, 0o644);
     }
 
+    const markdownBytes = `${redactSensitiveText(input.markdown).trimEnd()}\n`;
+    const markdownDescriptor = { path: `${slug}.md`, bytes: Buffer.byteLength(markdownBytes), sha256: createHash("sha256").update(markdownBytes).digest("hex") };
+    if (input.manifest.markdown !== undefined && (input.manifest.markdown.path !== markdownDescriptor.path || input.manifest.markdown.bytes !== markdownDescriptor.bytes || input.manifest.markdown.sha256 !== markdownDescriptor.sha256)) {
+      throw new Error("PDF Markdown does not match its manifest provenance");
+    }
+    const manifest = { ...input.manifest, markdown: markdownDescriptor };
     writeFileSync(
       join(stagingDirectory, `${slug}.md`),
-      `${redactSensitiveText(input.markdown).trimEnd()}\n`,
+      markdownBytes,
       { encoding: "utf8", flag: "wx", mode: 0o644 },
     );
     if (input.manifest.annotations === null) {
@@ -253,7 +259,7 @@ export function persistPdfCapture(input: PersistPdfCaptureInput): string {
     }
     writeFileSync(
       join(stagingDirectory, PDF_CAPTURE_MANIFEST_FILENAME),
-      `${JSON.stringify(input.manifest, null, 2)}\n`,
+      `${JSON.stringify(manifest, null, 2)}\n`,
       { encoding: "utf8", flag: "wx", mode: 0o644 },
     );
     assertStagingTreeSafe(stagingDirectory);

package/src/pdf/source.ts

@@ -1,3 +1,4 @@
+import { PdfCaptureError } from "./errors.js";
 import {
   chmodSync,
   mkdtempSync,
@@ -37,13 +38,13 @@ function parseRemoteUrl(input: string): URL | null {
   try {
     url = new URL(input);
   } catch {
-    throw new Error("PDF URL is invalid");
+    throw new PdfCaptureError("invalid-input", "PDF URL is invalid");
   }
   if (url.protocol !== "http:" && url.protocol !== "https:") {
-    throw new Error("PDF URL must use HTTP or HTTPS");
+    throw new PdfCaptureError("invalid-input", "PDF URL must use HTTP or HTTPS");
   }
   if (url.username !== "" || url.password !== "") {
-    throw new Error("PDF URL must not contain embedded credentials");
+    throw new PdfCaptureError("invalid-input", "PDF URL must not contain embedded credentials");
   }
   return url;
 }
@@ -69,7 +70,7 @@ function assertPdfSignature(bytes: Uint8Array): void {
     bytes.byteLength < 5
     || new TextDecoder().decode(bytes.subarray(0, 5)) !== "%PDF-"
   ) {
-    throw new Error("remote PDF input does not have a valid PDF signature");
+    throw new PdfCaptureError("invalid-input", "remote PDF input does not have a valid PDF signature");
   }
 }
 

package/src/pdf/tools.ts

@@ -1,3 +1,4 @@
+import { PdfCaptureError } from "./errors.js";
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
@@ -26,7 +27,7 @@ async function readBoundedStream(stream: NodeJS.ReadableStream, maxBytes: number
     if (typeof value === "string") chunk = new TextEncoder().encode(value);
     else if (value instanceof Uint8Array) chunk = value;
     else throw new Error("PDF tool returned an unsupported output chunk");
-    if (!bytes.append(chunk)) throw new Error(`PDF tool output exceeded ${maxBytes} bytes`);
+    if (!bytes.append(chunk)) throw new PdfCaptureError("limit-exceeded", `PDF tool output exceeded ${maxBytes} bytes`);
   }
   return new TextDecoder().decode(bytes.toUint8Array());
 }
@@ -37,7 +38,8 @@ export const runPdfToolCommand: PdfToolRunner = async (
 ): Promise<PdfToolCommandResult> => {
   const executable = specification.command[0];
   if (executable === undefined) throw new Error("PDF tool command is empty");
-  const useProcessGroup = process.platform !== "win32";
+  if (specification.processGroup !== undefined && !["new", "inherit"].includes(specification.processGroup)) throw new PdfCaptureError("invalid-input", "Invalid PDF process group policy");
+  const useProcessGroup = process.platform !== "win32" && specification.processGroup !== "inherit";
   const child = spawn(executable, specification.command.slice(1), {
     cwd: specification.cwd,
     detached: useProcessGroup,
@@ -51,7 +53,7 @@ export const runPdfToolCommand: PdfToolRunner = async (
     windowsHide: true,
   });
   const exited = new Promise<number>((resolveExit, rejectExit) => {
-    child.once("error", rejectExit);
+    child.once("error", (error: NodeJS.ErrnoException) => rejectExit(error.code === "ENOENT" ? new PdfCaptureError("tool-unavailable", "PDF tool executable is unavailable", { cause: error }) : error));
     child.once("close", (code) => resolveExit(code ?? 1));
   });
   const signalProcessTree = (signal: NodeJS.Signals): void => {
@@ -79,7 +81,7 @@ export const runPdfToolCommand: PdfToolRunner = async (
     forceKillTimer = setTimeout(() => signalProcessTree("SIGKILL"), 1_000);
   };
   const timer = setTimeout(() => {
-    requestStop(new Error(`PDF tool timed out after ${specification.timeoutMs}ms`));
+    requestStop(new PdfCaptureError("timeout", `PDF tool timed out after ${specification.timeoutMs}ms`));
   }, specification.timeoutMs);
 
   try {
@@ -137,10 +139,10 @@ export function resolvePdfTools(dependencies: PdfCaptureDependencies = {}): PdfT
     ? discoverExecutable("tesseract", dependencies)
     : dependencies.tools.tesseract;
   if (pdfinfo === null) {
-    throw new Error("pdfinfo is required for PDF ingestion; install the Poppler command-line tools");
+    throw new PdfCaptureError("tool-unavailable", "pdfinfo is required for PDF ingestion; install the Poppler command-line tools");
   }
   if (pdftohtml === null) {
-    throw new Error("pdftohtml is required for PDF ingestion; install the Poppler command-line tools");
+    throw new PdfCaptureError("tool-unavailable", "pdftohtml is required for PDF ingestion; install the Poppler command-line tools");
   }
   return { pdfinfo, pdftohtml, tesseract };
 }

package/src/pdf.ts

@@ -90,3 +90,13 @@ export type {
   PdfToolPaths,
   PdfToolRunner,
 } from "./pdf/model.js";
+
+import { inspectPdfCaptureBundle as inspectPdfCaptureBundleImplementation, verifyPdfCaptureBundle as verifyPdfCaptureBundleImplementation } from "./pdf/bundle-reader.js";
+import { PdfCaptureError as PdfCaptureErrorImplementation } from "./pdf/errors.js";
+export const inspectPdfCaptureBundle: typeof inspectPdfCaptureBundleImplementation = (...arguments_) => inspectPdfCaptureBundleImplementation(...arguments_);
+export const verifyPdfCaptureBundle: typeof verifyPdfCaptureBundleImplementation = (...arguments_) => verifyPdfCaptureBundleImplementation(...arguments_);
+export const PdfCaptureError = PdfCaptureErrorImplementation;
+export type PdfCaptureError = InstanceType<typeof PdfCaptureErrorImplementation>;
+export type { PdfCaptureErrorCode } from "./pdf/errors.js";
+export type { PdfBundleInspection, PdfBundleVerification, ReadPdfCaptureBundleOptions, PdfBundleIntegrity } from "./pdf/bundle-reader.js";
+export type { PdfQualityIssue } from "./pdf/model.js";

package/src/rerank-clef.ts

@@ -0,0 +1,52 @@
+import type { SearchReranker } from "./rerank.js";
+import { createHostedReranker, type SystemOneTransport, type TypeSafeRerankerOptions } from "./rerank-typesafe.js";
+
+export const CLEF_MODELS = ["clef", "clef-flash"] as const;
+export type ClefModel = (typeof CLEF_MODELS)[number];
+export const DEFAULT_CLEF_MODEL: ClefModel = "clef";
+export type ClefTransport = SystemOneTransport;
+export type ClefRerankerOptions = TypeSafeRerankerOptions & { readonly model?: ClefModel };
+
+export function clefEndpoint(accountId: string, model: ClefModel = DEFAULT_CLEF_MODEL): string {
+  if (typeof accountId !== "string" || !/^[a-f0-9]{32}$/u.test(accountId) || !CLEF_MODELS.includes(model)) {
+    throw new Error("Invalid Cloudflare Clef account or model.");
+  }
+  return `https://api.cloudflare.com/client/v4/accounts/${accountId}/ai/run/@cf/cloudflare/${model}`;
+}
+
+function unwrapClefResponse(value: unknown): unknown {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  const envelope = value as Record<string, unknown>;
+  if (envelope["success"] !== true || !Object.hasOwn(envelope, "result")
+    || (envelope["errors"] !== undefined && (!Array.isArray(envelope["errors"]) || envelope["errors"].length !== 0))) return null;
+  return envelope["result"];
+}
+
+export function createClefReranker(options: ClefRerankerOptions = {}): SearchReranker {
+  const environment = options.environment ?? process.env;
+  const accountId = Object.hasOwn(environment, "CLOUDFLARE_ACCOUNT_ID") ? environment["CLOUDFLARE_ACCOUNT_ID"] : undefined;
+  const apiKey = Object.hasOwn(environment, "CLOUDFLARE_API_TOKEN")
+    ? environment["CLOUDFLARE_API_TOKEN"]
+    : Object.hasOwn(environment, "CLOUDFLARE_AUTH_TOKEN") ? environment["CLOUDFLARE_AUTH_TOKEN"] : undefined;
+  const model = options.model === undefined ? DEFAULT_CLEF_MODEL : options.model;
+  let endpoint: string | undefined;
+  try { if (accountId !== undefined) endpoint = clefEndpoint(accountId, model); } catch { endpoint = undefined; }
+  const reranker = createHostedReranker(options, {
+    id: "clef", label: "Cloudflare Clef", model, endpoint, apiKey,
+    unavailableMessage: "Cloudflare Clef credentials or model are missing or invalid; set CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN.",
+    unwrap: unwrapClefResponse,
+  });
+  return {
+    id: reranker.id,
+    rerank: async (request) => {
+      try {
+        if (typeof request === "object" && request !== null && "images" in request) {
+          return { status: "failed", message: "Wordcell reranking accepts text only; image evidence is not supported." };
+        }
+        return await reranker.rerank(request);
+      } catch {
+        return { status: "failed", message: "Cloudflare Clef rerank request was malformed or failed." };
+      }
+    },
+  };
+}

package/src/rerank-credentials.ts

@@ -4,9 +4,10 @@ import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import type { SearchReranker } from "./rerank.js";
 import { createTypeSafeReranker } from "./rerank-typesafe.js";
+import { createClefReranker, type ClefModel } from "./rerank-clef.js";
 
-function unavailable(message: string): SearchReranker {
-  return { id: "typesafe", rerank: async () => ({ status: "unavailable", message }) };
+function unavailable(message: string, id = "typesafe"): SearchReranker {
+  return { id, rerank: async () => ({ status: "unavailable", message }) };
 }
 
 /** CLI-only credential discovery, called only after explicit --rerank typesafe. */
@@ -54,3 +55,11 @@ export async function createCliTypeSafeReranker(
     await handle?.close();
   }
 }
+
+export async function createCliClefReranker(
+  environment: Readonly<Record<string, string | undefined>> = process.env,
+  _homeDirectory: string = homedir(),
+  model: ClefModel = "clef",
+): Promise<SearchReranker> {
+  return createClefReranker({ environment, model });
+}

package/src/rerank-typesafe.ts

@@ -154,11 +154,11 @@ function tokenCount(value: unknown): number | null {
     : null;
 }
 
-function acceptedResponseModel(value: unknown): value is string {
-  return value === DEFAULT_SYSTEMONE_MODEL;
+function acceptedResponseModel(value: unknown, model: string): value is string {
+  return value === model;
 }
 
-function parseSystemOneResponse(value: unknown): ParsedSystemOneAnswer | null {
+function parseSystemOneResponse(value: unknown, model: string): ParsedSystemOneAnswer | null {
   const root = recordValue(value);
   if (root === null || !hasExactKeys(root, ["model", "answers", "usage"])) return null;
   const answers = recordValue(root["answers"]);
@@ -176,7 +176,7 @@ function parseSystemOneResponse(value: unknown): ParsedSystemOneAnswer | null {
   const inputTokens = tokenCount(usage["input_tokens"]);
   const outputTokens = tokenCount(usage["output_tokens"]);
   if (
-    !acceptedResponseModel(root["model"])
+    !acceptedResponseModel(root["model"], model)
     || inputTokens === null
     || outputTokens === null
   ) return null;
@@ -205,7 +205,7 @@ async function mapWithConcurrency<T, R>(
 }
 
 function validApiKey(value: string | undefined): value is string {
-  return value !== undefined && /^[\x21-\x7e]{1,512}$/u.test(value);
+  return typeof value === "string" && /^[\x21-\x7e]{1,512}$/u.test(value);
 }
 
 function boundedPositiveInteger(
@@ -274,6 +274,30 @@ type ScoredCandidate =
  */
 export function createTypeSafeReranker(
   options: TypeSafeRerankerOptions = {},
+): SearchReranker {
+  const environment = options.environment ?? process.env;
+  return createHostedReranker(options, {
+    id: "typesafe", label: "TypeSafe", model: DEFAULT_SYSTEMONE_MODEL,
+    endpoint: DEFAULT_SYSTEMONE_ENDPOINT,
+    apiKey: Object.hasOwn(environment, "TYPESAFE_API_KEY") ? environment["TYPESAFE_API_KEY"] : undefined,
+    unavailableMessage: "TYPESAFE_API_KEY is missing or invalid; the TypeSafe rerank lane is unavailable.",
+    unwrap: (value) => value,
+  });
+}
+
+export type HostedRerankProvider = {
+  readonly id: string;
+  readonly label: string;
+  readonly model: string;
+  readonly endpoint: string | undefined;
+  readonly apiKey: string | undefined;
+  readonly unavailableMessage: string;
+  readonly unwrap: (value: unknown) => unknown;
+};
+
+export function createHostedReranker(
+  options: TypeSafeRerankerOptions,
+  provider: HostedRerankProvider,
 ): SearchReranker {
   const transport = options.transport ?? fetchSystemOneTransport;
   const timeoutMs = boundedPositiveInteger(
@@ -291,13 +315,10 @@ export function createTypeSafeReranker(
     DEFAULT_RERANK_CONCURRENCY,
     MAX_RERANK_CONCURRENCY,
   );
-  const environment = options.environment ?? process.env;
-  const apiKey = Object.hasOwn(environment, "TYPESAFE_API_KEY")
-    ? environment["TYPESAFE_API_KEY"]
-    : undefined;
+  const apiKey = provider.apiKey;
 
   return {
-    id: "typesafe",
+    id: provider.id,
     rerank: async (request: SearchRerankRequest): Promise<SearchRerankResult> => {
       const started = performance.now();
       const controller = new AbortController();
@@ -330,7 +351,7 @@ export function createTypeSafeReranker(
         }),
       };
       const failed = (message: string): SearchRerankResult => ({
-        status: "failed", message, ...details(),
+        status: "failed", message: message.replaceAll("TypeSafe", provider.label), ...details(),
       });
       try {
         if (timeoutMs === null || maxResponseBytes === null || concurrency === null) {
@@ -344,8 +365,8 @@ export function createTypeSafeReranker(
         if (callerSignal?.aborted === true) {
           return failed("TypeSafe rerank request was aborted.");
         }
-        if (!validApiKey(apiKey)) {
-          return { status: "unavailable", message: "TYPESAFE_API_KEY is missing or invalid; the TypeSafe rerank lane is unavailable." };
+        if (!validApiKey(apiKey) || provider.endpoint === undefined) {
+          return { status: "unavailable", message: provider.unavailableMessage };
         }
         if (candidateCount === 0) return { status: "ready", ordering: [], probabilities: {} };
         const encoder = new TextEncoder();
@@ -359,12 +380,14 @@ export function createTypeSafeReranker(
           if (encoder.encode(JSON.stringify(state)).byteLength > MAX_RERANK_STATE_BYTES) {
             return failed(`TypeSafe rerank state exceeds the ${MAX_RERANK_STATE_BYTES}-byte limit.`);
           }
-          bodies.push(encoder.encode(JSON.stringify({
-            model: DEFAULT_SYSTEMONE_MODEL, state,
+          const body = encoder.encode(JSON.stringify({
+            model: provider.model, state,
             questions: { [RELEVANCE_QUESTION]: {
               type: "noul", instructions: RELEVANCE_INSTRUCTIONS, criteria: RELEVANCE_CRITERIA,
             } },
-          })));
+          }));
+          if (body.byteLength > 32 * 1_024) return failed("TypeSafe rerank body exceeds the 32768-byte limit.");
+          bodies.push(body);
         }
         const deadline = started + timeoutMs;
         const timeoutMessage = "TypeSafe rerank window exceeded its deadline.";
@@ -383,7 +406,7 @@ export function createTypeSafeReranker(
             let response: { readonly status: number; readonly body: Uint8Array };
             try {
               response = await transport({
-                url: DEFAULT_SYSTEMONE_ENDPOINT, body,
+                url: provider.endpoint!, body,
                 headers: { authorization: `Bearer ${apiKey}`, "content-type": "application/json" },
                 timeoutMs: Math.max(1, Math.ceil(deadline - performance.now())),
                 maxResponseBytes, signal: controller.signal,
@@ -412,7 +435,8 @@ export function createTypeSafeReranker(
                 return { ok: false, message: firstFailure! };
               }
               // Billing evidence is independent of whether the relevance answer is usable.
-              const root = recordValue(parsed);
+              const result = provider.unwrap(parsed);
+              const root = recordValue(result);
               const usage = recordValue(root?.["usage"]);
               const input = tokenCount(usage?.["input_tokens"]);
               const output = tokenCount(usage?.["output_tokens"]);
@@ -426,12 +450,12 @@ export function createTypeSafeReranker(
                 outputTokens += output;
                 usageReceipts += 1;
               }
-              if (acceptedResponseModel(root?.["model"])) observedModel = DEFAULT_SYSTEMONE_MODEL;
+              if (acceptedResponseModel(root?.["model"], provider.model)) observedModel = provider.model;
               if (response.status !== 200) {
                 stop(`TypeSafe rerank request returned HTTP ${response.status}.`);
                 return { ok: false, message: firstFailure! };
               }
-              const answer = parseSystemOneResponse(parsed);
+              const answer = parseSystemOneResponse(result, provider.model);
               if (answer === null) {
                 stop("TypeSafe rerank response was malformed.");
                 return { ok: false, message: firstFailure! };

package/src/rerank.ts

@@ -56,7 +56,7 @@ export type SearchReranker = {
 };
 
 export type KnowledgeBaseSearchRerankOptions = {
-  readonly engine: "typesafe";
+  readonly engine: "clef" | "typesafe";
   /** Window size submitted to the engine, from 2 through MAX_RERANK_CANDIDATES. */
   readonly limit?: number;
   /** Cancels only the hosted rerank phase, not local retrieval or indexing. */

package/src/sdk.ts

@@ -208,6 +208,7 @@ export type KnowledgeBaseSearchHit = {
 
 export type KnowledgeBaseSearchDiagnostic = {
   readonly lane: "exact" | "git" | "graph" | "qmd" | "rerank";
+  readonly engine?: string;
   /** Structured hosted-lane accounting, including known usage after fallback. */
   readonly rerank?: SearchRerankDetails;
   readonly status: "degraded" | "ready" | "unavailable";
@@ -560,8 +561,8 @@ function checkedRerankRequest(
     throw new TypeError("Search rerank options must be an options object.");
   }
   const options = value as KnowledgeBaseSearchRerankOptions;
-  if (options.engine !== "typesafe") {
-    throw new Error('Search rerank engine must be "typesafe".');
+  if (options.engine !== "clef" && options.engine !== "typesafe") {
+    throw new Error('Search rerank engine must be "clef" or legacy "typesafe".');
   }
   const reranker = rerankers?.find((entry) => entry.id === options.engine);
   if (reranker === undefined) {
@@ -1034,6 +1035,7 @@ export async function openKnowledgeBase(
         : (applied.message ?? "Rerank engine did not return a result.");
       diagnostics.push({
         lane: "rerank",
+        engine: rerankRequest.reranker.id,
         ...(Object.keys(resultDetails).length === 0 ? {} : { rerank: resultDetails }),
         status: applied.status === "failed" ? "degraded" : applied.status,
         results: applied.status === "ready" ? applied.placements.size : 0,