ochre-sdk 1.0.73 → 1.0.74

package/README.md

@@ -121,6 +121,34 @@ const result = await fetchSetItems(
 Use `fetchSetPropertyValues` with the same query shape when you need facet data
 for a filtered result set.
 
+### OCR Text Queries
+
+The `ocr` target searches the OCR text layer of the Resource items in a Set. It takes no `language`, because OCR text carries none.
+
+```ts
+const queries: Query = {
+  and: [
+    {
+      target: "ocr",
+      value: "Cappaert",
+      matchMode: "includes",
+      isCaseSensitive: false,
+    },
+    {
+      target: "title",
+      value: "Convocation",
+      matchMode: "includes",
+      isCaseSensitive: false,
+      language: "eng",
+    },
+  ],
+};
+```
+
+Every `<string>` node in that layer holds a single OCR word, so `includes` matches each search term as its own word anywhere in the layer, in any order, with `*` and `?` wildcards supported. `exact` instead matches the terms as a run of adjacent whole words, so `"THE COLLEGE"` matches a page carrying that phrase but not one where the two words merely appear apart. An item matches when the OCR layer of the item itself or of any of its child Resources matches.
+
+Set item projections do not carry the OCR layer, so an `ocr` leaf is resolved by an extra index-only search over the Resource documents whose matching UUIDs are then joined back onto the Set items. It still composes with `and`, `or`, and `isNegated` like any other leaf, and repeating the same OCR search inside one tree only costs one search.
+
 ## OCR Data
 
 A Resource may carry an `<ocr>` layer holding the positioned output of an OCR run. The node hierarchy inside that layer is irregular and is not parsed, but any `<string>` node within it, at any depth, is read as one positioned OCR string.
@@ -139,7 +167,7 @@ for (const ocrString of result.ocrStrings ?? []) {
 
 `x` and `y` come from `HPOS` and `VPOS` and give the top-left corner of the box, `width` and `height` its size, and `vertices` its full bounding polygon, which is not always rectangular. Each geometry field is null when the source attribute is absent or unparseable. `resourceUuid` names the Resource that owns the OCR layer, which differs from the requested item when the OCR lives on a child Resource.
 
-Matching defaults to case-insensitive `includes` and runs against each string's `CONTENT`. Because a `<string>` holds a single OCR word, a multi-word search value is split on whitespace and a string is returned when it matches any one term, which pairs with how the `ocrText` query target tokenizes. Requesting an item that does not exist is an error; an item with no OCR layer, or no matches, returns an empty array.
+Matching defaults to case-insensitive `includes` and runs against each string's `CONTENT`. Because a `<string>` holds a single OCR word, a multi-word search value is split on whitespace and a string is returned when it matches any one term. Requesting an item that does not exist is an error; an item with no OCR layer, or no matches, returns an empty array.
 
 ## Helpers And Types
 

package/dist/fetchers/set/items.mjs

@@ -4,7 +4,7 @@ import { iso639_3Schema, setItemsParametersSchema } from "../../schemas.mjs";
 import { restoreXMLMetadata } from "../../xml/metadata.mjs";
 import { parseSetItems } from "../../parsers/index.mjs";
 import { XMLSetItemsData } from "../../xml/schemas.mjs";
-import { buildAndCtsQueryExpression, buildBelongsToCollectionQueryExpression, buildQueryPlan } from "../../query.mjs";
+import { buildBelongsToCollectionQueryExpression, buildQueryPlan } from "../../query.mjs";
 import * as v from "valibot";
 import { XMLParser } from "fast-xml-parser";
 //#region src/fetchers/set/items.ts
@@ -138,9 +138,11 @@ function buildXQuery(parameters) {
 	const { queries, sort, setScopeUuids, belongsToCollectionScopeUuids, page, pageSize } = parameters;
 	const startPosition = (page - 1) * pageSize + 1;
 	const setScopeDeclaration = `declare variable $setScopeUuids := (${setScopeUuids.map((uuid) => stringLiteral(uuid)).join(", ")});`;
-	const compiledQueryPlan = buildQueryPlan({ queries });
-	const baseItemsExpression = "doc()/ochre/set[@uuid = $setScopeUuids]/items/*";
-	const belongsToCollectionQueryExpression = buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, BELONGS_TO_COLLECTION_UUID);
+	const compiledQueryPlan = buildQueryPlan({
+		queries,
+		baseItemsExpression: "doc()/ochre/set[@uuid = $setScopeUuids]/items/*",
+		scopeQueryExpression: buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, BELONGS_TO_COLLECTION_UUID)
+	});
 	const orderedItemsClause = buildOrderedItemsClause(sort);
 	const xqueryDeclarations = [
 		"xquery version \"1.0-ml\";",
@@ -148,28 +150,10 @@ function buildXQuery(parameters) {
 		SUPPLEMENTAL_XQUERY_PROLOG
 	];
 	if (compiledQueryPlan.prolog !== "") xqueryDeclarations.push(compiledQueryPlan.prolog);
-	const letClauses = Array.from(compiledQueryPlan.ocrTextBindings, (binding) => `let ${binding.name} := ${binding.expression}`);
-	const branchExpressions = [];
-	for (const [index, branch] of compiledQueryPlan.branches.entries()) {
-		const branchQueryExpressions = [];
-		if (branch.queryExpression != null) branchQueryExpressions.push(branch.queryExpression);
-		if (belongsToCollectionQueryExpression != null) branchQueryExpressions.push(belongsToCollectionQueryExpression);
-		const branchQueryExpression = buildAndCtsQueryExpression(branchQueryExpressions);
-		const branchItemsExpression = `${baseItemsExpression}${branch.itemPredicates}`;
-		if (branchQueryExpression == null) {
-			branchExpressions.push(branchItemsExpression);
-			continue;
-		}
-		const queryVariableName = compiledQueryPlan.branches.length === 1 ? "$query" : `$query${index + 1}`;
-		letClauses.push(`let ${queryVariableName} := ${branchQueryExpression}`);
-		branchExpressions.push(`cts:search(${branchItemsExpression}, ${queryVariableName})`);
-	}
-	letClauses.push(`let $items := ${branchExpressions.length === 1 ? branchExpressions[0] : `(${branchExpressions.join(" | ")})`}`);
-	const itemsClause = letClauses.join("\n  ");
 	return `${xqueryDeclarations.join("\n\n")}
 
 <ochre>{
-${itemsClause}
+${compiledQueryPlan.itemsClause}
   let $totalCount := count($items)
   ${orderedItemsClause}
   let $pagedItems := subsequence($orderedItems, ${startPosition}, ${pageSize})

package/dist/fetchers/set/property-values.mjs

@@ -3,7 +3,7 @@ import { NOT_SUPPLEMENTAL_PREDICATE, createSchemaValidationError, getErrorOutput
 import { MultilingualString } from "../../parsers/multilingual.mjs";
 import { setPropertyValuesParametersSchema } from "../../schemas.mjs";
 import { parseXMLContent } from "../../parsers/string.mjs";
-import { buildAndCtsQueryExpression, buildBelongsToCollectionQueryExpression, buildQueryPlan } from "../../query.mjs";
+import { buildBelongsToCollectionQueryExpression, buildQueryPlan } from "../../query.mjs";
 import * as v from "valibot";
 import { XMLParser } from "fast-xml-parser";
 //#region src/fetchers/set/property-values.ts
@@ -190,9 +190,11 @@ const responseSchema = v.object({ result: v.object({ ochre: v.object({
 function buildXQuery(parameters) {
 	const { setScopeUuids, belongsToCollectionScopeUuids, queries, propertyFacetSelectors, attributes, isLimitedToLeafPropertyValues } = parameters;
 	const setScopeDeclaration = `declare variable $setScopeUuids := (${setScopeUuids.map((uuid) => stringLiteral(uuid)).join(", ")});`;
-	const compiledQueryPlan = buildQueryPlan({ queries: getItemFilterQueriesFromPropertyValueQueries(queries) });
-	const baseItemsExpression = "doc()/ochre/set[@uuid = $setScopeUuids]/items/*";
-	const belongsToCollectionQueryExpression = buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, BELONGS_TO_COLLECTION_UUID);
+	const compiledQueryPlan = buildQueryPlan({
+		queries: getItemFilterQueriesFromPropertyValueQueries(queries),
+		baseItemsExpression: "doc()/ochre/set[@uuid = $setScopeUuids]/items/*",
+		scopeQueryExpression: buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, BELONGS_TO_COLLECTION_UUID)
+	});
 	const valueFilter = isLimitedToLeafPropertyValues ? "[not(@i)]" : "";
 	const queryBlocks = [];
 	const returnedSequences = [];
@@ -400,28 +402,10 @@ let $period-values :=
   )`);
 		returnedSequences.push("$period-values");
 	}
-	const letClauses = Array.from(compiledQueryPlan.ocrTextBindings, (binding) => `let ${binding.name} := ${binding.expression}`);
-	const branchExpressions = [];
-	for (const [index, branch] of compiledQueryPlan.branches.entries()) {
-		const branchQueryExpressions = [];
-		if (branch.queryExpression != null) branchQueryExpressions.push(branch.queryExpression);
-		if (belongsToCollectionQueryExpression != null) branchQueryExpressions.push(belongsToCollectionQueryExpression);
-		const branchQueryExpression = buildAndCtsQueryExpression(branchQueryExpressions);
-		const branchItemsExpression = `${baseItemsExpression}${branch.itemPredicates}`;
-		if (branchQueryExpression == null) {
-			branchExpressions.push(branchItemsExpression);
-			continue;
-		}
-		const queryVariableName = compiledQueryPlan.branches.length === 1 ? "$query" : `$query${index + 1}`;
-		letClauses.push(`let ${queryVariableName} := ${branchQueryExpression}`);
-		branchExpressions.push(`cts:search(${branchItemsExpression}, ${queryVariableName})`);
-	}
-	letClauses.push(`let $items := ${branchExpressions.length === 1 ? branchExpressions[0] : `(${branchExpressions.join(" | ")})`}`);
-	const itemsClause = letClauses.join("\n  ");
 	return `${xqueryDeclarations.join("\n\n")}
 
 <ochre>{
-${itemsClause}
+${compiledQueryPlan.itemsClause}
 ${queryBlocks.join("\n\n")}
 
 return (${returnedSequences.join(", ")})

package/dist/fetchers/website.mjs

@@ -6,7 +6,7 @@ import { parseWebsite } from "../parsers/website/index.mjs";
 import * as v from "valibot";
 import { XMLParser } from "fast-xml-parser";
 //#region src/fetchers/website.ts
-async function validateWebsiteCredentials(uuid, credentials, fetcher) {
+async function areWebsiteCredentialsValid(uuid, credentials, fetcher) {
 	const security = typeof credentials === "string" ? { validate: credentials } : {
 		validate: credentials.password,
 		userOCHRE: credentials.username
@@ -69,7 +69,7 @@ async function fetchWebsite(abbreviation, options) {
 				error: null,
 				detailedError: null
 			};
-			if (!await validateWebsiteCredentials(website.uuid, options.credentials, fetcher)) throw new Error("Invalid credentials for protected website");
+			if (!await areWebsiteCredentialsValid(website.uuid, options.credentials, fetcher)) throw new Error("Invalid credentials for protected website");
 		}
 		return {
 			website,

package/dist/getters.d.mts

@@ -4,9 +4,13 @@ import { LanguageCodes, Property, PropertyLike, PropertyValueContent, SetItemPro
  * Options for property search operations.
  */
 type PropertyOptions = {
-  /** Whether to recursively search through nested properties. */
+  /**
+    Whether to recursively search through nested properties.
+    */
   includeNestedProperties?: boolean;
-  /** Whether to limit property values to leaf values. */
+  /**
+    Whether to limit property values to leaf values.
+    */
   limitToLeafPropertyValues?: boolean;
 };
 type PropertyContent<T extends LanguageCodes> = PropertyValueContent<T>["content"];

package/dist/parsers/multilingual.d.mts

@@ -26,11 +26,17 @@ type MultilingualStringEntries<T extends ReadonlyArray<string> = ReadonlyArray<s
  * Options for creating and working with multilingual strings
  */
 type MultilingualOptions = {
-  /** Default language to use for fallbacks */
+  /**
+    Default language to use for fallbacks
+    */
   defaultLanguage?: string;
-  /** Available languages for this string */
+  /**
+    Available languages for this string
+    */
   availableLanguages?: ReadonlyArray<string>;
-  /** Alias values carried by OCHRE as zxx content */
+  /**
+    Alias values carried by OCHRE as zxx content
+    */
   aliases?: ReadonlyArray<string>;
 };
 type MultilingualContent<T extends ReadonlyArray<string>> = Partial<Record<T[number], ReadonlyArray<MultilingualStringEntry>>>;
@@ -78,7 +84,9 @@ declare class MultilingualString<T extends ReadonlyArray<string> = ReadonlyArray
   /**
    * Create a new multilingual string from an object of language codes to text.
    */
-  /** @internal */
+  /**
+    @internal
+    */
   constructor(init: MultilingualStringInternalInit<T>);
   constructor(content: MultilingualStringObject<T>, languages: T, options?: MultilingualOptions);
   constructor(content?: Partial<Record<string, MultilingualStringInput>>, languages?: undefined, options?: MultilingualOptions);

package/dist/parsers/website/index.mjs

@@ -907,17 +907,18 @@ function parseWebpage(webpageResource, options, context, slugPrefix) {
 		returnWebpage.properties.isNavbarSearchBarDisplayed = pageReader.valueOr("navbar-search-bar-displayed", true);
 		const redirectValue = pageReader.valueNode("redirect-to");
 		const redirectTarget = parseWebsiteLinkTarget(redirectValue, context);
-		if (redirectTarget != null) if (redirectValue?.href == null && redirectValue?.uuid != null) returnWebpage.properties.redirect = {
-			type: "page",
-			slug: redirectTarget,
-			uuid: redirectValue.uuid
-		};
-		else returnWebpage.properties.redirect = {
-			type: "url",
-			href: redirectTarget,
-			isExternal: redirectTarget.startsWith("http")
-		};
-		else if (redirectValue?.uuid != null) returnWebpage.properties.redirect = {
+		if (redirectTarget != null) {
+			if (redirectValue?.href == null && redirectValue?.uuid != null) returnWebpage.properties.redirect = {
+				type: "page",
+				slug: redirectTarget,
+				uuid: redirectValue.uuid
+			};
+			else returnWebpage.properties.redirect = {
+				type: "url",
+				href: redirectTarget,
+				isExternal: redirectTarget.startsWith("http")
+			};
+		} else if (redirectValue?.uuid != null) returnWebpage.properties.redirect = {
 			type: "item",
 			uuid: redirectValue.uuid,
 			pageType: "item"
@@ -1015,7 +1016,7 @@ function parseSidebar(resources, options, context) {
 			}
 		}
 	}
-	if (items.length > 0 && title != null) returnSidebar = {
+	if (title != null && items.length > 0) returnSidebar = {
 		isDisplayed: true,
 		items,
 		title,

package/dist/query.d.mts

@@ -1,31 +1,32 @@
 import { Query } from "./types/index.mjs";
 //#region src/query.d.ts
-declare function buildAndCtsQueryExpression(queryExpressions: Array<string>): string | null;
 declare function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids: Array<string>, belongsToCollectionPropertyVariableUuid: string): string | null;
 /**
- * Compile a query tree into the CTS searches that resolve it
+ * Compile a query tree into the XQuery `let` clauses that bind `$items` to the
+ * matching Set items
  *
- * OCR text is not carried by Set item projections, so an `ocrText` leaf cannot
- * be a CTS term: it resolves to a document join whose UUID list can only be
- * applied as an item path predicate, and path predicates only ever AND. To keep
- * `ocrText` composable with `or` anyway, the tree is split on each distinct OCR
- * text condition, one branch per assignment of "this item is in that match
- * set". Every branch is a plain CTS search, and their union is the result.
- * Branches that the assignment already rules out are dropped, so a query whose
- * OCR text leaves are all conjunctive still compiles to a single search.
+ * Most queries compile to a single `cts:search` over the Set item projections.
+ * An `ocr` leaf cannot: the projections drop the `<ocr>` layer, so it resolves
+ * to a search over the Resource documents whose matching UUIDs are joined back
+ * in as an item path predicate. Path predicates only ever AND, so an `ocr` leaf
+ * that sits under an `or` becomes its own arm of a node union instead, and one
+ * that sits under an `and` alongside a union becomes an intersection.
+ *
+ * The searchable path has to stay inline in `cts:search`: binding it to a
+ * variable first makes every query XDMP-UNSEARCHABLE.
+ * @param parameters - The parameters for the compilation
+ * @param parameters.queries - Recursive query tree to compile, if any
+ * @param parameters.baseItemsExpression - The inline XQuery path selecting the items to search
+ * @param parameters.scopeQueryExpression - An optional CTS query ANDed into every compiled search
+ * @returns The prolog declaring the query helpers, and the `let` clauses binding `$items`
  */
 declare function buildQueryPlan(parameters: {
   queries: Query | null;
+  baseItemsExpression: string;
+  scopeQueryExpression?: string | null;
 }): {
   prolog: string;
-  ocrTextBindings: Array<{
-    name: string;
-    expression: string;
-  }>;
-  branches: Array<{
-    itemPredicates: string;
-    queryExpression: string | null;
-  }>;
+  itemsClause: string;
 };
 //#endregion
-export { buildAndCtsQueryExpression, buildBelongsToCollectionQueryExpression, buildQueryPlan };
+export { buildBelongsToCollectionQueryExpression, buildQueryPlan };

package/dist/query.mjs

@@ -12,7 +12,6 @@ const CTS_INCLUDES_STOP_WORDS = /* @__PURE__ */ new Set([
 const CTS_INCLUDES_TOKEN_WORD_REGEX = /^\p{L}+$/u;
 const CTS_INCLUDES_TOKEN_REGEX = /[\p{L}\p{N}*?]+/gu;
 const CTS_EXACT_TEXT_TOKEN_REGEX = /[\p{L}\p{N}]+/gu;
-const MAX_OCR_TEXT_CONDITIONS = 4;
 const CONTENT_TARGET_CONTENT_ELEMENT_PATHS = {
 	title: [
 		"identification",
@@ -239,7 +238,8 @@ function buildRichTextContentQueryExpression(parameters) {
 	const { value, matchMode, isCaseSensitive, language } = parameters;
 	return buildAndCtsQueryExpressionInternal([buildContentLanguageQuery(language), matchMode === "exact" ? buildRichTextExactQueryExpression({
 		value,
-		isCaseSensitive
+		isCaseSensitive,
+		language
 	}) : buildCtsWordQueryExpression({
 		value,
 		matchMode,
@@ -472,83 +472,81 @@ function buildItemStringQueryExpression(parameters) {
 		language
 	})]);
 }
-function buildOcrTextQueryExpression(query) {
+function tokenizeOcrPhraseValue(value) {
+	const terms = [];
+	for (const term of value.split(/\s+/u)) if (term !== "") terms.push(term);
+	return terms;
+}
+/**
+* Word queries against the OCR layer cannot carry a stemming option: the OCHRE
+* database has unstemmed word searches turned off, and asking an element word
+* query for `unstemmed` fails with `XDMP-WORDSEARCH`. Omitting the option
+* altogether resolves the term against the database default instead.
+*/
+function buildOcrWordQueryExpression(parameters) {
+	const { value, isCaseSensitive } = parameters;
+	const options = [
+		isCaseSensitive ? "case-sensitive" : "case-insensitive",
+		"diacritic-insensitive",
+		"punctuation-insensitive",
+		"whitespace-insensitive"
+	];
+	if (hasWildcardCharacters(value)) options.push("wildcarded");
+	return `cts:element-word-query(xs:QName("string"), ${stringLiteral(value)}, (${options.map((option) => stringLiteral(option)).join(", ")}))`;
+}
+/**
+* Compile an OCR text search into a query over the `<ocr>` layer of a Resource
+* document
+*
+* Every `<string>` node in that layer holds a single OCR word, so `includes`
+* matches each search term as its own word anywhere in the layer, and `exact`
+* matches the terms as a run of adjacent whole string values. A phrase cannot
+* be a word query here: word positions do not carry across the `<string>`
+* boundaries, which makes `cts:near-query` the only phrase mechanism, and its
+* distance is a total span rather than a pairwise gap.
+*/
+function buildOcrQueryExpression(query) {
 	const { value, matchMode, isCaseSensitive } = query;
-	const phraseQueryExpression = buildRichTextPhraseQueryExpression({
-		value,
-		isCaseSensitive
-	});
-	if (matchMode === "exact") return buildNestedElementQuery(["ocrText"], phraseQueryExpression);
+	if (matchMode === "exact") {
+		const terms = tokenizeOcrPhraseValue(value);
+		if (terms.length === 0) return "cts:false-query()";
+		const termQueryExpressions = Array.from(terms, (term) => buildCtsElementValueQueryExpression({
+			elementName: "string",
+			value: term,
+			isCaseSensitive
+		}));
+		return buildNestedElementQuery(["ocr"], termQueryExpressions.length === 1 ? termQueryExpressions[0] ?? "cts:false-query()" : `cts:near-query((${termQueryExpressions.join(", ")}), ${termQueryExpressions.length - 1}, ("ordered"))`);
+	}
 	const terms = tokenizeIncludesSearchValue({
 		value,
 		isCaseSensitive
 	});
 	if (terms.length === 0) return "cts:false-query()";
-	const tokenizedQueryExpression = buildAndCtsQueryExpressionInternal(Array.from(terms, (term) => buildCtsWordQueryExpression({
+	return buildNestedElementQuery(["ocr"], buildAndCtsQueryExpressionInternal(Array.from(terms, (term) => buildOcrWordQueryExpression({
 		value: term,
-		matchMode,
-		isCaseSensitive,
-		queryFamily: "text"
-	})));
-	return buildNestedElementQuery(["ocrText"], shouldUseFullValueFallbackForIncludes({
-		value,
-		isCaseSensitive,
-		terms
-	}) ? buildOrCtsQueryExpressionInternal([phraseQueryExpression, tokenizedQueryExpression]) : tokenizedQueryExpression);
+		isCaseSensitive
+	}))));
 }
-function getOcrTextConditionKey(query) {
-	return [
+/**
+* Bind the UUIDs of the Resource documents whose OCR layer matches a query,
+* reusing the binding when the same search is requested more than once
+*/
+function registerOcrBinding(context, query) {
+	const key = [
 		query.value,
 		query.matchMode,
 		query.isCaseSensitive ? "case-sensitive" : "case-insensitive"
 	].join("|");
-}
-function registerOcrTextCondition(context, query) {
-	const key = getOcrTextConditionKey(query);
-	if (context.ocrTextConditionIndexesByKey.has(key)) return;
-	context.ocrTextConditionIndexesByKey.set(key, context.ocrTextConditions.length);
-	context.ocrTextConditions.push({
-		variableName: `$ocrTextUuids${context.ocrTextConditions.length + 1}`,
-		bindingExpression: `for $ocrTextDocument in cts:search(doc(), ${buildOcrTextQueryExpression(query)})\n    return document-uri($ocrTextDocument)`
+	const existingName = context.ocrBindingNamesByKey.get(key);
+	if (existingName != null) return existingName;
+	const name = `$ocrItemUuids${context.ocrBindings.length + 1}`;
+	const queryExpression = buildOcrQueryExpression(query);
+	context.ocrBindingNamesByKey.set(key, name);
+	context.ocrBindings.push({
+		name,
+		expression: queryExpression === "cts:false-query()" ? "()" : `cts:search(/ochre/resource, ${queryExpression})/@uuid/string()`
 	});
-}
-function collectOcrTextConditions(context, query) {
-	if (isQueryLeaf(query)) {
-		if (query.target === "ocrText") registerOcrTextCondition(context, query);
-		return;
-	}
-	for (const childQuery of getQueryGroupChildren(query)) collectOcrTextConditions(context, childQuery);
-}
-function isOcrTextLeafMatched(context, query, ocrTextValues) {
-	const conditionIndex = context.ocrTextConditionIndexesByKey.get(getOcrTextConditionKey(query));
-	const isMatched = conditionIndex != null && ocrTextValues[conditionIndex] === true;
-	return query.isNegated === true ? !isMatched : isMatched;
-}
-/**
-* Enumerate every assignment of "this item is in the OCR text match set" across
-* the compiled conditions, least significant position first
-*/
-function getOcrTextValueCombinations(count) {
-	return Array.from({ length: 2 ** count }, (_, index) => Array.from({ length: count }, (_, position) => (index >> position & 1) === 1));
-}
-/**
-* Resolve a query tree against one OCR text assignment, treating every CTS leaf
-* as unknown. Only a definite `false` is actionable: it means the branch cannot
-* match anything and can be dropped before it costs a `cts:search`.
-*/
-function evaluateOcrTextBranch(context, query, ocrTextValues) {
-	if (isQueryLeaf(query)) return query.target === "ocrText" ? isOcrTextLeafMatched(context, query, ocrTextValues) : null;
-	const isAndGroup = "and" in query;
-	let result = isAndGroup;
-	for (const childQuery of getQueryGroupChildren(query)) {
-		const childResult = evaluateOcrTextBranch(context, childQuery, ocrTextValues);
-		if (childResult === !isAndGroup) return !isAndGroup;
-		if (childResult == null) result = null;
-	}
-	return result;
-}
-function buildOcrTextItemPredicates(context, ocrTextValues) {
-	return Array.from(context.ocrTextConditions, (condition, index) => ocrTextValues[index] === true ? `[@uuid = ${condition.variableName}]` : `[not(@uuid = ${condition.variableName})]`).join("");
+	return name;
 }
 function getLeafSearchValue(query) {
 	switch (query.target) {
@@ -631,8 +629,8 @@ function createQueryCompilerContext() {
 		nextHelperSerial: 1,
 		helperNamesByKey: /* @__PURE__ */ new Map(),
 		helperDeclarations: [],
-		ocrTextConditions: [],
-		ocrTextConditionIndexesByKey: /* @__PURE__ */ new Map()
+		ocrBindingNamesByKey: /* @__PURE__ */ new Map(),
+		ocrBindings: []
 	};
 }
 function registerConstantHelper(parameters) {
@@ -833,7 +831,7 @@ function getCompatibleIncludesGroupLeaves(query) {
 	if (!("or" in query) || query.or.length <= 1) return null;
 	const leafQueries = [];
 	for (const childQuery of query.or) {
-		if (!isQueryLeaf(childQuery) || childQuery.target === "ocrText") return null;
+		if (!isQueryLeaf(childQuery) || childQuery.target === "ocr") return null;
 		leafQueries.push(childQuery);
 	}
 	const firstQuery = leafQueries[0];
@@ -894,16 +892,121 @@ function buildIncludesGroupQueryExpression(context, queries) {
 		bodyExpression: buildOrCtsQueryExpressionInternal(exactMemberHelpers.map((helper) => helper.callExpression))
 	}).callExpression, tokenizedQueryExpression]);
 }
-function buildQueryNode(context, query, ocrTextValues) {
+function buildCtsItemsPlan(queryExpression) {
+	return {
+		kind: "search",
+		itemPredicates: [],
+		queryExpressions: [queryExpression]
+	};
+}
+/**
+* Splice the children of same-kind child plans into their parent, so that a
+* nested group of the same operator does not cost an extra search
+*/
+function flattenItemsPlans(childPlans, kind) {
+	const flattenedPlans = [];
+	for (const childPlan of childPlans) {
+		if (childPlan.kind === kind) {
+			flattenedPlans.push(...childPlan.children);
+			continue;
+		}
+		flattenedPlans.push(childPlan);
+	}
+	return flattenedPlans;
+}
+/**
+* Fold the children of an `and` group into one plan
+*
+* Conjunction is the direction the item path predicates already run in, so
+* every child that is a plain search collapses into a single search, and only
+* the children that resolved to a union stay separate.
+*/
+function buildAndItemsPlan(childPlans) {
+	const mergedPlan = {
+		kind: "search",
+		itemPredicates: [],
+		queryExpressions: []
+	};
+	const unfoldablePlans = [];
+	for (const childPlan of flattenItemsPlans(childPlans, "intersect")) {
+		if (childPlan.kind !== "search") {
+			unfoldablePlans.push(childPlan);
+			continue;
+		}
+		for (const itemPredicate of childPlan.itemPredicates) if (!mergedPlan.itemPredicates.includes(itemPredicate)) mergedPlan.itemPredicates.push(itemPredicate);
+		mergedPlan.queryExpressions.push(...childPlan.queryExpressions);
+	}
+	if (unfoldablePlans.length === 0) return mergedPlan;
+	const intersectedPlans = mergedPlan.itemPredicates.length === 0 && mergedPlan.queryExpressions.length === 0 ? unfoldablePlans : [mergedPlan, ...unfoldablePlans];
+	return intersectedPlans.length === 1 ? intersectedPlans[0] ?? mergedPlan : {
+		kind: "intersect",
+		children: intersectedPlans
+	};
+}
+/**
+* Fold the children of an `or` group into one plan
+*
+* Item path predicates cannot be disjoined, so a child carrying one becomes its
+* own arm of a node union. Everything else is still a single CTS query.
+*/
+function buildOrItemsPlan(childPlans) {
+	const mergedQueryExpressions = [];
+	const unionedPlans = [];
+	for (const childPlan of flattenItemsPlans(childPlans, "union")) {
+		if (childPlan.kind === "search" && childPlan.itemPredicates.length === 0) {
+			mergedQueryExpressions.push(buildAndCtsQueryExpressionInternal(childPlan.queryExpressions));
+			continue;
+		}
+		unionedPlans.push(childPlan);
+	}
+	if (mergedQueryExpressions.length > 0) unionedPlans.unshift({
+		kind: "search",
+		itemPredicates: [],
+		queryExpressions: [buildOrCtsQueryExpressionInternal(mergedQueryExpressions)]
+	});
+	if (unionedPlans.length === 0) return buildCtsItemsPlan("cts:false-query()");
+	return unionedPlans.length === 1 ? unionedPlans[0] ?? buildCtsItemsPlan("cts:false-query()") : {
+		kind: "union",
+		children: unionedPlans
+	};
+}
+function buildItemsPlan(context, query) {
 	if (isQueryLeaf(query)) {
-		if (query.target === "ocrText") return isOcrTextLeafMatched(context, query, ocrTextValues) ? "cts:true-query()" : "cts:false-query()";
+		if (query.target === "ocr") {
+			const bindingName = registerOcrBinding(context, query);
+			return {
+				kind: "search",
+				itemPredicates: [query.isNegated === true ? `[not(@uuid = ${bindingName})]` : `[@uuid = ${bindingName}]`],
+				queryExpressions: []
+			};
+		}
 		const queryExpression = buildLeafQueryExpression(context, query);
-		return query.isNegated === true ? buildNotCtsQueryExpression(queryExpression) : queryExpression;
+		return buildCtsItemsPlan(query.isNegated === true ? buildNotCtsQueryExpression(queryExpression) : queryExpression);
 	}
 	const optimizedIncludesGroupQueries = getCompatibleIncludesGroupLeaves(query);
-	if (optimizedIncludesGroupQueries != null) return buildIncludesGroupQueryExpression(context, optimizedIncludesGroupQueries);
-	const childQueryExpressions = Array.from(getQueryGroupChildren(query), (childQuery) => buildQueryNode(context, childQuery, ocrTextValues));
-	return (getQueryGroupOperator(query) === "and" ? buildAndCtsQueryExpressionInternal : buildOrCtsQueryExpressionInternal)(childQueryExpressions);
+	if (optimizedIncludesGroupQueries != null) return buildCtsItemsPlan(buildIncludesGroupQueryExpression(context, optimizedIncludesGroupQueries));
+	const childPlans = Array.from(getQueryGroupChildren(query), (childQuery) => buildItemsPlan(context, childQuery));
+	return getQueryGroupOperator(query) === "and" ? buildAndItemsPlan(childPlans) : buildOrItemsPlan(childPlans);
+}
+function collectItemsSearchPlans(plan, searchPlans) {
+	if (plan.kind === "search") {
+		searchPlans.push(plan);
+		return;
+	}
+	for (const childPlan of plan.children) collectItemsSearchPlans(childPlan, searchPlans);
+}
+function buildItemsPlanExpression(parameters) {
+	const { plan, baseItemsExpression, queryNamesByPlan } = parameters;
+	if (plan.kind === "search") {
+		const itemsExpression = `${baseItemsExpression}${plan.itemPredicates.join("")}`;
+		const queryName = queryNamesByPlan.get(plan);
+		return queryName == null ? itemsExpression : `cts:search(${itemsExpression}, ${queryName})`;
+	}
+	return `(${Array.from(plan.children, (childPlan) => buildItemsPlanExpression({
+		plan: childPlan,
+		baseItemsExpression,
+		queryNamesByPlan
+	})).join(plan.kind === "union" ? " | " : " intersect ")})`;
 }
 function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, belongsToCollectionPropertyVariableUuid) {
 	if (belongsToCollectionScopeUuids.length === 0) return null;
@@ -917,46 +1020,58 @@ function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids,
 	});
 }
 /**
-* Compile a query tree into the CTS searches that resolve it
+* Compile a query tree into the XQuery `let` clauses that bind `$items` to the
+* matching Set items
+*
+* Most queries compile to a single `cts:search` over the Set item projections.
+* An `ocr` leaf cannot: the projections drop the `<ocr>` layer, so it resolves
+* to a search over the Resource documents whose matching UUIDs are joined back
+* in as an item path predicate. Path predicates only ever AND, so an `ocr` leaf
+* that sits under an `or` becomes its own arm of a node union instead, and one
+* that sits under an `and` alongside a union becomes an intersection.
 *
-* OCR text is not carried by Set item projections, so an `ocrText` leaf cannot
-* be a CTS term: it resolves to a document join whose UUID list can only be
-* applied as an item path predicate, and path predicates only ever AND. To keep
-* `ocrText` composable with `or` anyway, the tree is split on each distinct OCR
-* text condition, one branch per assignment of "this item is in that match
-* set". Every branch is a plain CTS search, and their union is the result.
-* Branches that the assignment already rules out are dropped, so a query whose
-* OCR text leaves are all conjunctive still compiles to a single search.
+* The searchable path has to stay inline in `cts:search`: binding it to a
+* variable first makes every query XDMP-UNSEARCHABLE.
+* @param parameters - The parameters for the compilation
+* @param parameters.queries - Recursive query tree to compile, if any
+* @param parameters.baseItemsExpression - The inline XQuery path selecting the items to search
+* @param parameters.scopeQueryExpression - An optional CTS query ANDed into every compiled search
+* @returns The prolog declaring the query helpers, and the `let` clauses binding `$items`
 */
 function buildQueryPlan(parameters) {
-	const { queries } = parameters;
-	if (queries == null) return {
-		prolog: "",
-		ocrTextBindings: [],
-		branches: [{
-			itemPredicates: "",
-			queryExpression: null
-		}]
-	};
+	const { queries, baseItemsExpression, scopeQueryExpression } = parameters;
 	const context = createQueryCompilerContext();
-	collectOcrTextConditions(context, queries);
-	if (context.ocrTextConditions.length > MAX_OCR_TEXT_CONDITIONS) throw new Error(`A query cannot contain more than ${MAX_OCR_TEXT_CONDITIONS} distinct OCR text searches`, { cause: context.ocrTextConditions.length });
-	const branches = [];
-	for (const ocrTextValues of getOcrTextValueCombinations(context.ocrTextConditions.length)) {
-		if (evaluateOcrTextBranch(context, queries, ocrTextValues) === false) continue;
-		branches.push({
-			itemPredicates: buildOcrTextItemPredicates(context, ocrTextValues),
-			queryExpression: buildQueryNode(context, queries, ocrTextValues)
+	const plan = queries == null ? {
+		kind: "search",
+		itemPredicates: [],
+		queryExpressions: []
+	} : buildItemsPlan(context, queries);
+	const searchPlans = [];
+	collectItemsSearchPlans(plan, searchPlans);
+	const boundSearchPlans = [];
+	for (const searchPlan of searchPlans) {
+		const queryExpression = buildAndCtsQueryExpression([...searchPlan.queryExpressions, ...scopeQueryExpression == null ? [] : [scopeQueryExpression]]);
+		if (queryExpression != null) boundSearchPlans.push({
+			plan: searchPlan,
+			queryExpression
 		});
 	}
+	const queryNamesByPlan = /* @__PURE__ */ new Map();
+	const letClauses = Array.from(context.ocrBindings, (binding) => `let ${binding.name} := ${binding.expression}`);
+	for (const [index, boundSearchPlan] of boundSearchPlans.entries()) {
+		const queryName = boundSearchPlans.length === 1 ? "$query" : `$query${index + 1}`;
+		queryNamesByPlan.set(boundSearchPlan.plan, queryName);
+		letClauses.push(`let ${queryName} := ${boundSearchPlan.queryExpression}`);
+	}
+	letClauses.push(`let $items := ${buildItemsPlanExpression({
+		plan,
+		baseItemsExpression,
+		queryNamesByPlan
+	})}`);
 	return {
 		prolog: context.helperDeclarations.join("\n\n"),
-		ocrTextBindings: Array.from(context.ocrTextConditions, (condition) => ({
-			name: condition.variableName,
-			expression: condition.bindingExpression
-		})),
-		branches
+		itemsClause: letClauses.join("\n  ")
 	};
 }
 //#endregion
-export { buildAndCtsQueryExpression, buildBelongsToCollectionQueryExpression, buildQueryPlan };
+export { buildBelongsToCollectionQueryExpression, buildQueryPlan };

package/dist/schemas.mjs

@@ -142,7 +142,7 @@ const setQueryLeafSchema = v.union([
 		...standardQueryFields
 	}),
 	v.strictObject({
-		target: v.literal("ocrText"),
+		target: v.literal("ocr"),
 		value: v.string(),
 		matchMode: standardQueryFields.matchMode,
 		isCaseSensitive: standardQueryFields.isCaseSensitive,

package/dist/types/index.d.mts

@@ -815,12 +815,13 @@ type SetItemsSort = {
 /**
  * Represents a leaf query for Set items
  *
- * The `ocrText` target matches the OCR text layer of Resource items. Because
- * Set item projections do not carry `<ocrText>`, it is resolved by a document
- * join rather than a CTS term, so it composes with `and`, `or`, and `isNegated`
- * at the cost of one extra search branch per distinct OCR text value in a
- * disjunction. OCR text carries no language, so `ocrText` leaves take no
- * `language`.
+ * The `ocr` target matches the OCR text layer of Resource items. Set item
+ * projections do not carry `<ocr>`, so it is resolved by a document join rather
+ * than by a CTS term, and it composes with `and`, `or`, and `isNegated` at the
+ * cost of one extra search per distinct OCR value. Each `<string>` in that
+ * layer holds a single OCR word, so `includes` matches every search term as its
+ * own word and `exact` matches the terms as an adjacent run of whole words. OCR
+ * text carries no language, so `ocr` leaves take no `language`.
  */
 type QueryLeaf = {
   target: "property";
@@ -888,7 +889,7 @@ type QueryLeaf = {
   language: string;
   isNegated?: boolean;
 } | {
-  target: "ocrText";
+  target: "ocr";
   value: string;
   matchMode: "includes" | "exact";
   isCaseSensitive: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ochre-sdk",
-  "version": "1.0.73",
+  "version": "1.0.74",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",
@@ -51,11 +51,12 @@
     "valibot": "^1.4.2"
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^9.2.0",
+    "@antfu/eslint-config": "^9.3.0",
     "@types/node": "^24.13.3",
     "bumpp": "^12.2.0",
     "eslint": "^10.8.0",
-    "knip": "^6.31.0",
+    "eslint-plugin-erasable-syntax-only": "^0.4.2",
+    "knip": "^6.32.0",
     "oxfmt": "^0.62.0",
     "tsdown": "^0.22.14",
     "typescript": "^6.0.3",