@farming-labs/docs 0.2.120 → 0.2.121

package/dist/search.mjs

@@ -0,0 +1,3401 @@
+import { filterDocsPagesByAccess } from "./access.mjs";
+import { resolveDocsOkfTrustMetadata } from "./okf.mjs";
+import { isDocsMcpResourcePath } from "./mcp-auth.mjs";
+import { PAGE_AGENT_CONTRACT_END_MARKER, PAGE_AGENT_CONTRACT_START_MARKER, renderPageAgentContractMarkdown, upsertPageAgentContractMarkdown } from "./agent-contract.mjs";
+import { findDocsGeneratedAgentContractRanges, findDocsMarkdownSection, parseDocsMarkdownSections, stripDocsGeneratedAgentContractMarkers } from "./markdown-sections.mjs";
+import { digestDocsRetrievalContent, isDocsRetrievalCanonicalUrl } from "./retrieval-digest.mjs";
+import { DocsPaginationCursorError, createDocsPaginationCursor, paginateDocsItems, resolveDocsPaginationCursor } from "./pagination.mjs";
+import { agentVersionConstraintGroupsOverlap, agentVersionConstraintsOverlap, normalizeAgentFramework, normalizeAgentLocale, normalizeAgentScopeValues, normalizeAgentVersion } from "./agent-scope.mjs";
+import { resolveDocsAudienceMdxContent } from "./audience.mjs";
+
+//#region src/search.ts
+const DEFAULT_SEARCH_LIMIT = 10;
+const MAX_STRUCTURED_SEARCH_LIMIT = 25;
+const MAX_SEARCH_SNIPPET_CHARS = 160;
+const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
+const MCP_SESSION_CLEANUP_TIMEOUT_MS = 1e3;
+const syncedIndexes = /* @__PURE__ */ new Map();
+const syncingIndexes = /* @__PURE__ */ new Map();
+const ALGOLIA_MAX_RECORD_BYTES = 9500;
+const DEFAULT_ASK_AI_CONTEXT_CHARS = 24e3;
+const DEFAULT_ASK_AI_RESULT_CHARS = 6e3;
+const MAX_SEARCH_FILTER_VALUES = 16;
+const MAX_SEARCH_FILTER_VALUE_CHARS = 128;
+const MAX_SEARCH_FILTER_RAW_CHARS = 4096;
+const MAX_SEARCH_FILTER_SEGMENTS = 64;
+const MAX_SEARCH_PROVIDER_CURSOR_STATE_CHARS = 1024;
+const MAX_PROVIDER_SCOPE_FILTER_IDS = 1e3;
+const MAX_PROVIDER_SCOPE_FILTER_CHARS = 16e3;
+const MAX_HOSTED_PROVIDER_CURSOR_RESULTS = 1e3;
+const MAX_MCP_SEARCH_CURSOR_REPLAY_PAGES = 64;
+const MAX_MCP_SEARCH_CURSOR_RESULTS = MAX_MCP_SEARCH_CURSOR_REPLAY_PAGES;
+const DOCS_UNPAGINATED_PROVIDER_QUERY = Symbol("docs-unpaginated-provider-query");
+const DOCS_PROVIDER_SCOPE_FILTER_OVERFLOW = Symbol("docs-provider-scope-filter-overflow");
+const ALGOLIA_BATCH_OPERATIONS = 1e3;
+const MAX_SEARCH_WARNINGS = 16;
+const MAX_SEARCH_WARNING_VALUES = 16;
+const MAX_SEARCH_WARNING_PAGE_URLS = 8;
+const MAX_SEARCH_FACET_VALUES = 100;
+const MAX_SEARCH_EXPLANATION_TERMS = 32;
+const MAX_SEARCH_EXPLANATION_TERM_CHARS = 128;
+const RETRIEVAL_INDEX_FORMAT = "docs-retrieval-index.v1";
+const MAX_RETRIEVAL_SOURCE_URL_CHARS = 4096;
+const MAX_RETRIEVAL_SOURCE_VALUE_CHARS = 256;
+const SEARCH_FILTER_FIELDS = [
+	"framework",
+	"version",
+	"package",
+	"tags"
+];
+const SEARCH_AMBIGUITY_FIELDS = [
+	"framework",
+	"version",
+	"package"
+];
+const SEARCH_STOP_WORDS = new Set([
+	"a",
+	"an",
+	"and",
+	"are",
+	"as",
+	"at",
+	"be",
+	"can",
+	"do",
+	"does",
+	"for",
+	"from",
+	"how",
+	"i",
+	"in",
+	"is",
+	"it",
+	"of",
+	"on",
+	"or",
+	"the",
+	"this",
+	"to",
+	"use",
+	"what",
+	"when",
+	"where",
+	"which",
+	"with"
+]);
+function normalizeDocsSearchFilterValue(field, value) {
+	const bounded = value.trim().slice(0, MAX_SEARCH_FILTER_VALUE_CHARS).trim();
+	if (!bounded) return "";
+	if (field === "framework") return normalizeAgentFramework(bounded);
+	if (field === "version") return normalizeAgentVersion(bounded);
+	return bounded.toLowerCase();
+}
+function normalizeDocsSearchFilterValues(field, input) {
+	const values = typeof input === "string" ? [input] : input ?? [];
+	const normalized = [];
+	const seen = /* @__PURE__ */ new Set();
+	let remainingChars = MAX_SEARCH_FILTER_RAW_CHARS;
+	let remainingSegments = MAX_SEARCH_FILTER_SEGMENTS;
+	for (const item of values) {
+		if (remainingChars <= 0 || remainingSegments <= 0) break;
+		const boundedItem = item.slice(0, remainingChars);
+		remainingChars -= boundedItem.length;
+		for (const part of boundedItem.split(",")) {
+			if (remainingSegments <= 0) break;
+			remainingSegments -= 1;
+			const value = normalizeDocsSearchFilterValue(field, part);
+			if (!value || seen.has(value)) continue;
+			seen.add(value);
+			normalized.push(value);
+			if (normalized.length >= MAX_SEARCH_FILTER_VALUES) return normalized;
+		}
+	}
+	return normalized;
+}
+/** Normalize scalar or array-valued scope filters for programmatic, HTTP, and MCP callers. */
+function normalizeDocsSearchFilters(input = {}) {
+	const filters = {};
+	for (const field of SEARCH_FILTER_FIELDS) {
+		const values = normalizeDocsSearchFilterValues(field, input[field]);
+		if (values.length > 0) filters[field] = values;
+	}
+	return filters;
+}
+/** Parse the public search scope parameters from a URL query string. */
+function resolveDocsSearchFilters(searchParams) {
+	return normalizeDocsSearchFilters({
+		framework: searchParams.getAll("framework"),
+		version: searchParams.getAll("version"),
+		package: searchParams.getAll("package"),
+		tags: searchParams.getAll("tags")
+	});
+}
+var DocsSearchRequestError = class extends Error {
+	code = "invalid_search_request";
+	constructor(message) {
+		super(message);
+		this.name = "DocsSearchRequestError";
+	}
+};
+function resolveDocsSearchError(error) {
+	if (error instanceof DocsPaginationCursorError) return {
+		code: error.code,
+		message: error.message
+	};
+	if (error instanceof DocsSearchRequestError) return {
+		code: error.code,
+		message: error.message
+	};
+}
+/** Resolve search filters and the backwards-compatible structured response opt-in. */
+function resolveDocsSearchRequest(searchParams) {
+	const response = searchParams.get("response");
+	const structured = response === "structured";
+	const facets = response === "facets";
+	const rawExplain = searchParams.get("explain");
+	if (rawExplain !== null && rawExplain !== "true" && rawExplain !== "false") throw new DocsSearchRequestError("Search explain must be `true` or `false`.");
+	const explain = rawExplain === "true";
+	const rawFacet = searchParams.get("facet");
+	let facet;
+	if (rawFacet !== null) {
+		if (!facets || !SEARCH_FILTER_FIELDS.includes(rawFacet)) throw new DocsSearchRequestError("Search facet must be one of framework, version, package, or tags and requires `response=facets`.");
+		facet = rawFacet;
+	}
+	const cursor = searchParams.get("cursor") ?? void 0;
+	if (cursor !== void 0 && !structured && !facets) throw new DocsSearchRequestError("Search cursors require `response=structured` or `response=facets`.");
+	if (cursor !== void 0 && facets && facet === void 0) throw new DocsSearchRequestError("Facet continuation cursors require a `facet` field.");
+	if (cursor !== void 0 && (cursor.length === 0 || cursor.length > 4096 || !/^[A-Za-z\d_-]+$/u.test(cursor))) throw new DocsPaginationCursorError();
+	const rawLimit = searchParams.get("limit");
+	let limit;
+	if (rawLimit !== null && (structured || facets)) {
+		const maximum = facets ? MAX_SEARCH_FACET_VALUES : MAX_STRUCTURED_SEARCH_LIMIT;
+		if (!/^\d+$/u.test(rawLimit)) throw new DocsSearchRequestError(`Search limit must be an integer between 1 and ${maximum}.`);
+		limit = Number(rawLimit);
+		if (!Number.isSafeInteger(limit) || limit < 1 || limit > maximum) throw new DocsSearchRequestError(`Search limit must be an integer between 1 and ${maximum}.`);
+	}
+	return {
+		filters: resolveDocsSearchFilters(searchParams),
+		structured,
+		...explain ? { explain: true } : {},
+		...facets ? { facets: true } : {},
+		...facet !== void 0 ? { facet } : {},
+		...cursor !== void 0 ? { cursor } : {},
+		...limit !== void 0 ? { limit } : {}
+	};
+}
+function hasDocsSearchFilters(filters) {
+	return SEARCH_FILTER_FIELDS.some((field) => (filters[field]?.length ?? 0) > 0);
+}
+function resolveProviderScopeDocumentIds(query, context, corpusId) {
+	if (!hasDocsSearchFilters(query.filters ?? {})) return void 0;
+	const documents = corpusId ? buildDocsSearchDocuments(context.pages, context.chunking ?? { strategy: "section" }, "human") : context.documents;
+	const ids = Array.from(new Set(documents.map((document) => corpusId ? makeHostedProviderDocumentId(corpusId, document.id) : document.id)));
+	return ids.length <= MAX_PROVIDER_SCOPE_FILTER_IDS ? ids : DOCS_PROVIDER_SCOPE_FILTER_OVERFLOW;
+}
+function docsSearchFiltersMatch(expected, actual) {
+	return SEARCH_FILTER_FIELDS.every((field) => {
+		const expectedValues = expected[field] ?? [];
+		const actualValues = actual[field] ?? [];
+		return expectedValues.length === actualValues.length && expectedValues.every((value) => actualValues.includes(value));
+	});
+}
+function parseVerifiedMcpSearchFilters(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+	const record = value;
+	const filterFields = SEARCH_FILTER_FIELDS;
+	if (Object.keys(record).some((field) => !filterFields.includes(field))) return;
+	const input = {};
+	for (const field of SEARCH_FILTER_FIELDS) {
+		const values = record[field];
+		if (values === void 0) continue;
+		if (!Array.isArray(values) || values.length > MAX_SEARCH_FILTER_VALUES || values.some((item) => typeof item !== "string" || item.length > MAX_SEARCH_FILTER_VALUE_CHARS)) return;
+		input[field] = values;
+	}
+	const normalized = normalizeDocsSearchFilters(input);
+	for (const field of SEARCH_FILTER_FIELDS) {
+		const values = record[field];
+		if (values === void 0) continue;
+		if (!Array.isArray(values) || values.length !== (normalized[field]?.length ?? 0) || values.some((value, index) => value !== normalized[field]?.[index])) return;
+	}
+	return normalized;
+}
+function normalizeDocsSearchMetadataValues(field, value) {
+	const values = normalizeAgentScopeValues(value);
+	return Array.from(new Set(values.map((item) => normalizeDocsSearchFilterValue(field, item)).filter((item) => Boolean(item))));
+}
+function valuesOverlap(left, right, matches) {
+	return left.some((leftValue) => right.some((rightValue) => matches(leftValue, rightValue)));
+}
+function resolveDocsSearchPageScope(page) {
+	const topFramework = normalizeDocsSearchMetadataValues("framework", page.framework);
+	const contractFramework = normalizeDocsSearchMetadataValues("framework", page.agent?.appliesTo?.framework);
+	const topVersion = normalizeDocsSearchMetadataValues("version", page.version);
+	const contractVersion = normalizeDocsSearchMetadataValues("version", page.agent?.appliesTo?.version);
+	const packageValues = normalizeDocsSearchMetadataValues("package", page.agent?.appliesTo?.package);
+	const tags = normalizeDocsSearchMetadataValues("tags", page.tags);
+	const conflicts = [];
+	if (topFramework.length > 0 && contractFramework.length > 0 && !valuesOverlap(topFramework, contractFramework, (left, right) => left === right)) conflicts.push("framework");
+	if (topVersion.length > 0 && contractVersion.length > 0 && !valuesOverlap(topVersion, contractVersion, agentVersionConstraintsOverlap)) conflicts.push("version");
+	return {
+		framework: topFramework.length > 0 && contractFramework.length > 0 ? topFramework.filter((value) => contractFramework.includes(value)) : Array.from(new Set([...topFramework, ...contractFramework])),
+		version: Array.from(new Set([...topVersion, ...contractVersion])),
+		package: packageValues,
+		tags,
+		declarations: {
+			framework: [topFramework, contractFramework].filter((values) => values.length > 0),
+			version: [topVersion, contractVersion].filter((values) => values.length > 0),
+			package: packageValues.length > 0 ? [packageValues] : [],
+			tags: tags.length > 0 ? [tags] : []
+		},
+		conflicts
+	};
+}
+function docsSearchScopeValueMatches(field, requested, candidate) {
+	return field === "version" ? agentVersionConstraintsOverlap(requested, candidate) : requested === candidate;
+}
+function docsSearchPageMatchesFilters(scope, filters) {
+	if (scope.conflicts.length > 0) return false;
+	return SEARCH_FILTER_FIELDS.every((field) => {
+		const requested = filters[field];
+		if (!requested || requested.length === 0) return true;
+		return docsSearchScopeFieldMatches(scope, field, requested);
+	});
+}
+function docsSearchScopeFieldMatches(scope, field, requested) {
+	const declarations = scope.declarations[field];
+	if (declarations.length === 0) return false;
+	if (field === "version") return agentVersionConstraintGroupsOverlap([requested, ...declarations]);
+	return requested.some((value) => declarations.every((candidates) => candidates.some((candidate) => docsSearchScopeValueMatches(field, value, candidate))));
+}
+function stripMarkdownText(content) {
+	return removeMdxModuleLinesOutsideFences(content).replace(/```[^\n]*\n([\s\S]*?)```/g, "$1").replace(/```([\s\S]*?)```/g, "$1").replace(/~~~[^\n]*\n([\s\S]*?)~~~/g, "$1").replace(/~~~([\s\S]*?)~~~/g, "$1").replace(/<[^>]+\/>/g, "").replace(/<\/?[A-Z][^>]*>/g, "").replace(/<\/?[a-z][^>]*>/g, "").replace(/!\[([^\]]*)\]\([^)]+\)/g, "$1").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/^#{1,6}\s+/gm, "").replace(/^\|?[\s:-]+(\|[\s:-]+)+\|?\s*$/gm, "").replace(/\|/g, " ").replace(/^[-*+]\s+/gm, "").replace(/(\*{1,3}|_{1,3})(.*?)\1/g, "$2").replace(/`{3,}[^\n]*$/gm, "").replace(/`([^`]+)`/g, "$1").replace(/`+/g, "").replace(/^>\s+/gm, "").replace(/^[-*_]{3,}\s*$/gm, "").replace(/\n{3,}/g, "\n\n").replace(/\s{2,}/g, " ").trim();
+}
+function stripHtml(text) {
+	return text.replace(/<[^>]+>/g, "");
+}
+function normalizeMcpSsePayload(body) {
+	const payload = body.split("\n").filter((line) => line.startsWith("data: ")).map((line) => line.slice(6).trim()).filter(Boolean).at(-1);
+	return payload ? JSON.parse(payload) : null;
+}
+function normalizeWhitespace(value) {
+	return value.replace(/\s+/g, " ").trim();
+}
+function normalizeSearchPhrase(value) {
+	return normalizeWhitespace(value.toLowerCase().replace(/[?!.,;:]+$/g, ""));
+}
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function literalMatchPriority(query, value) {
+	const q = normalizeSearchPhrase(query);
+	const text = normalizeSearchPhrase(value ?? "");
+	if (!q || !text) return 0;
+	if (text === q) return 2;
+	const boundary = "[^\\p{L}\\p{N}]";
+	return new RegExp(`(^|${boundary})${escapeRegExp(q)}(?=$|${boundary})`, "u").test(text) ? 1 : 0;
+}
+function isLiteralLookupQuery(query) {
+	const q = normalizeSearchPhrase(query);
+	const words = tokenizeSearchQuery(q);
+	return words.length > 0 && words.length <= 3 && words.join(" ") === q;
+}
+function tokenizeSearchQuery(query) {
+	return Array.from(new Set(query.toLowerCase().replace(/[^\p{L}\p{N}@/_:.-]+/gu, " ").split(/\s+/).map((word) => word.replace(/^[^\p{L}\p{N}@]+|[^\p{L}\p{N}]+$/gu, "")).filter((word) => word.length > 1 && !SEARCH_STOP_WORDS.has(word))));
+}
+function normalizeUrlRouteKey(value) {
+	try {
+		const url = new URL(value, "https://docs.local");
+		return `${url.pathname || "/"}${url.search}`;
+	} catch {
+		return value.split("#", 1)[0] || "/";
+	}
+}
+function normalizeAuthoredUrlIdentity(value) {
+	const trimmed = value.trim();
+	const explicitScheme = trimmed.match(/^([a-z][a-z\d+.-]*):/iu)?.[1]?.toLowerCase();
+	if (explicitScheme && explicitScheme !== "http" && explicitScheme !== "https") return normalizeUrlRouteKey("/");
+	try {
+		const url = new URL(trimmed, "https://docs.local");
+		const route = `${url.pathname || "/"}${url.search}`;
+		if (explicitScheme) return `${url.origin}${route}`;
+		if (trimmed.startsWith("//")) return `//${url.host}${route}`;
+		return route;
+	} catch {
+		return normalizeUrlRouteKey(trimmed);
+	}
+}
+function appendDocsLocaleQuery(value, locale) {
+	const hashIndex = value.indexOf("#");
+	const withoutHash = hashIndex >= 0 ? value.slice(0, hashIndex) : value;
+	const hash = hashIndex >= 0 ? value.slice(hashIndex) : "";
+	const queryIndex = withoutHash.indexOf("?");
+	const rawQuery = queryIndex >= 0 ? withoutHash.slice(queryIndex + 1) : "";
+	if (new URLSearchParams(rawQuery).has("lang")) return value;
+	return `${withoutHash}${queryIndex >= 0 ? "&" : "?"}lang=${encodeURIComponent(locale)}${hash}`;
+}
+function localizeDocsSearchPage(page, localeFallback) {
+	const rawLocale = (page.locale ?? localeFallback)?.trim();
+	if (!rawLocale) return page;
+	const locale = rawLocale;
+	const url = appendDocsLocaleQuery(page.url, locale);
+	if (url === page.url && page.locale === locale) return page;
+	return {
+		...page,
+		url,
+		locale
+	};
+}
+function safeDecodeUrlSegment(value) {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return value;
+	}
+}
+function getUrlSearchSegments(value) {
+	let pathname = "";
+	try {
+		pathname = new URL(value, "https://docs.local").pathname;
+	} catch {
+		pathname = value.split(/[?#]/)[0] ?? "";
+	}
+	return Array.from(new Set(pathname.split("/").flatMap((segment) => {
+		const decoded = safeDecodeUrlSegment(segment);
+		return [decoded, decoded.replace(/[-_]+/g, " ")];
+	}).map(normalizeSearchPhrase).filter(Boolean)));
+}
+function resolveAskAIContextUrl(value, baseUrl) {
+	if (!baseUrl) return value;
+	try {
+		return new URL(value, baseUrl).toString();
+	} catch {
+		return value;
+	}
+}
+function cleanGeneratedAgentContractMarkers(content) {
+	return stripDocsGeneratedAgentContractMarkers(content);
+}
+function getAskAIPageSectionContent(page) {
+	return getPageAudienceSectionContent(page, "agent");
+}
+function getAskAIPageContent(page) {
+	return cleanGeneratedAgentContractMarkers(getAskAIPageSectionContent(page));
+}
+function getPageAgentContractSearchText(page) {
+	return stripMarkdownText(renderPageAgentContractMarkdown(page.agent).replace(PAGE_AGENT_CONTRACT_START_MARKER, "").replace(PAGE_AGENT_CONTRACT_END_MARKER, ""));
+}
+function removeMdxModuleLinesOutsideFences(content) {
+	let inFence = false;
+	return content.split("\n").filter((line) => {
+		const trimmed = line.trimStart();
+		if (trimmed.startsWith("```") || trimmed.startsWith("~~~")) {
+			inFence = !inFence;
+			return true;
+		}
+		return inFence || !/^(import|export)\s/.test(trimmed);
+	}).join("\n");
+}
+function cleanAskAIContextMarkdown(content) {
+	return removeMdxModuleLinesOutsideFences(content).replace(/<[^>]+\/>/g, "").replace(/<\/?[A-Z][^>]*>/g, "").replace(/<\/?[a-z][^>]*>/g, "").replace(/\n{3,}/g, "\n\n").trim();
+}
+function packageRootFromSpecifier(specifier) {
+	if (!specifier || specifier.startsWith(".") || specifier.startsWith("/") || specifier.startsWith("@/") || specifier.startsWith("~/") || specifier.startsWith("#")) return null;
+	const parts = specifier.split("/").filter(Boolean);
+	if (parts.length === 0) return null;
+	if (parts[0]?.startsWith("@")) return parts.length > 1 ? `${parts[0]}/${parts[1]}` : null;
+	return parts[0];
+}
+function cleanPackageToken(token) {
+	const trimmed = token.trim().replace(/^["'`]+|["'`,;]+$/g, "").replace(/\\$/g, "");
+	if (!trimmed || trimmed.startsWith("-") || /^[A-Z_][A-Z0-9_]*=/.test(trimmed)) return null;
+	if (/^(npm|pnpm|yarn|bun|install|add|i|x|dlx|run|exec)$/.test(trimmed)) return null;
+	return packageRootFromSpecifier(trimmed.startsWith("@") ? trimmed.replace(/^(@[^/]+\/[^@]+)@.+$/, "$1") : trimmed.replace(/^([^@]+)@.+$/, "$1"));
+}
+function inferDocsAskAIPackageHints(content) {
+	const packages = /* @__PURE__ */ new Set();
+	const imports = /* @__PURE__ */ new Set();
+	const installCommands = /* @__PURE__ */ new Set();
+	for (const line of content.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		const importSpecifier = trimmed.match(/^(?:import|export)\s+(?:type\s+)?[\s\S]*?\s+from\s+["']([^"']+)["']/)?.[1];
+		const bareImportSpecifier = trimmed.match(/^import\s+["']([^"']+)["']/)?.[1];
+		const requireSpecifier = trimmed.match(/require\(["']([^"']+)["']\)/)?.[1];
+		const specifier = importSpecifier ?? bareImportSpecifier ?? requireSpecifier;
+		const packageName = specifier ? packageRootFromSpecifier(specifier) : null;
+		if (packageName) {
+			packages.add(packageName);
+			if (/^(?:import|export)\s/.test(trimmed)) imports.add(trimmed);
+		}
+		const installMatch = trimmed.match(/^(?:npm\s+(?:install|i)|pnpm\s+add|yarn\s+add|bun\s+add)\s+(.+)$/);
+		if (!installMatch) continue;
+		const commandPackages = installMatch[1].split(/\s+/).map(cleanPackageToken).filter((value) => Boolean(value));
+		if (commandPackages.length > 0) {
+			installCommands.add(trimmed);
+			for (const name of commandPackages) packages.add(name);
+		}
+	}
+	return {
+		packages: Array.from(packages).slice(0, 8),
+		imports: Array.from(imports).slice(0, 12),
+		installCommands: Array.from(installCommands).slice(0, 8)
+	};
+}
+function formatDocsAskAIPackageHints(hints, packageName) {
+	const packages = packageName ? Array.from(new Set([packageName, ...hints.packages])) : hints.packages;
+	if (packages.length === 0 && hints.imports.length === 0 && hints.installCommands.length === 0) return;
+	const lines = ["Package and import hints inferred from the retrieved documentation context:"];
+	if (packages.length > 0) lines.push(`- Package names found in install/import examples: ${packages.join(", ")}`);
+	if (hints.imports.length > 0) lines.push(`- Exact import lines found in context: ${hints.imports.map((line) => `\`${line}\``).join("; ")}`);
+	if (hints.installCommands.length > 0) lines.push(`- Exact install commands found in context: ${hints.installCommands.map((line) => `\`${line}\``).join("; ")}`);
+	lines.push("Use these exact package names, install commands, and import lines when relevant. Do not replace them with placeholders.");
+	return lines.join("\n");
+}
+function clampText(value, maxChars) {
+	if (maxChars <= 0) return "";
+	if (value.length <= maxChars) return value;
+	return `${value.slice(0, maxChars).trimEnd()}...`;
+}
+function findPageForSearchResult(pages, result, baseUrl, pagesByRoute) {
+	const rawUrl = result.url.trim();
+	const explicitlySchemed = /^[a-z][a-z\d+.-]*:/iu.test(rawUrl);
+	const explicitlyHosted = explicitlySchemed || /^[\\/]{2}/u.test(rawUrl);
+	if (explicitlySchemed && !/^https?:/iu.test(rawUrl)) return void 0;
+	if (explicitlyHosted && !baseUrl) return void 0;
+	if (explicitlyHosted && baseUrl) try {
+		if (new URL(result.url, baseUrl).origin !== new URL(baseUrl).origin) return void 0;
+	} catch {
+		return;
+	}
+	const resultPath = normalizeUrlRouteKey(result.url);
+	return pagesByRoute?.get(resultPath) ?? pages.find((page) => normalizeUrlRouteKey(page.url) === resultPath);
+}
+function inferResultTitle(result, page) {
+	if (page) return page.title;
+	return stripHtml(result.content).trim().split("—")[0]?.trim() || result.url;
+}
+function formatAskAIContextResult(options) {
+	const { result, page, maxChars, baseUrl } = options;
+	const title = inferResultTitle(result, page);
+	const section = result.section;
+	const sectionSelector = getSearchResultAnchor(result.url) ?? section;
+	const contextContent = clampText(cleanAskAIContextMarkdown(page ? sectionSelector ? cleanGeneratedAgentContractMarkers(findDocsMarkdownSection(getAskAIPageSectionContent(page), sectionSelector)?.content ?? "") : getAskAIPageContent(page) : [result.content, result.description].filter(Boolean).join("\n\n")), maxChars);
+	return {
+		...result,
+		url: resolveAskAIContextUrl(result.url, baseUrl),
+		title,
+		contextContent
+	};
+}
+function getSearchResultKey(result) {
+	const anchor = getSearchResultAnchor(result.url);
+	const sectionFallback = normalizeWhitespace(result.section ?? "").toLowerCase();
+	return `${normalizeUrlRouteKey(result.url)}#${anchor ?? sectionFallback}`;
+}
+function getSearchResultAnchor(value) {
+	let hash = "";
+	try {
+		hash = new URL(value, "https://docs.local").hash.replace(/^#/, "");
+	} catch {
+		const hashIndex = value.indexOf("#");
+		hash = hashIndex >= 0 ? value.slice(hashIndex + 1) : "";
+	}
+	if (!hash) return void 0;
+	try {
+		return decodeURIComponent(hash);
+	} catch {
+		return hash;
+	}
+}
+function getAskAIResultPageKey(value, baseUrl, strictExternalOrigins = false) {
+	const path = normalizeUrlRouteKey(value);
+	const rawValue = value.trim();
+	if (!(/^[a-z][a-z\d+.-]*:/iu.test(rawValue) || /^[\\/]{2}/u.test(rawValue)) || !baseUrl && !strictExternalOrigins) return path;
+	try {
+		const fallbackBase = baseUrl ?? "https://docs.local";
+		const parsed = new URL(value, fallbackBase);
+		const configuredBase = baseUrl ? new URL(baseUrl) : void 0;
+		if (configuredBase && parsed.origin === configuredBase.origin) return path;
+		return `${parsed.protocol}//${parsed.host}${path}`;
+	} catch {
+		return `${value.split("#", 1)[0]}::${path}`;
+	}
+}
+function getAskAIResultKey(result, baseUrl, strictExternalOrigins = false) {
+	const anchor = getSearchResultAnchor(result.url);
+	const sectionFallback = normalizeWhitespace(result.section ?? "").toLowerCase();
+	return `${getAskAIResultPageKey(result.url, baseUrl, strictExternalOrigins)}#${anchor ?? sectionFallback}`;
+}
+function mergeSearchResults(groups, getResultKey = getSearchResultKey) {
+	const seen = /* @__PURE__ */ new Set();
+	const results = [];
+	for (const group of groups) for (const result of group) {
+		const key = getResultKey(result);
+		if (seen.has(key)) continue;
+		seen.add(key);
+		results.push(result);
+	}
+	return results;
+}
+function buildAudienceProjectionSearchResults(documents, query) {
+	return documents.map((document) => {
+		const score = scoreDocument(query, document);
+		return {
+			id: document.id,
+			url: document.url,
+			content: document.section ? `${document.title} — ${document.section}` : document.title,
+			description: cleanSearchResultText(buildSnippet(document, query) ?? document.description),
+			type: document.type,
+			score,
+			section: document.section
+		};
+	});
+}
+function sanitizeExternalAudienceSearchResults(results, localAudienceResults, baseUrl, preserveUnmatched, fallbackSectionToLocalPage = false) {
+	const localByKey = new Map(localAudienceResults.map((result) => [getSearchResultKey(result), result]));
+	const localPageResults = /* @__PURE__ */ new Map();
+	for (const result of localAudienceResults) {
+		const pageUrl = normalizeUrlRouteKey(result.url);
+		if (!localPageResults.get(pageUrl) || result.type === "page") localPageResults.set(pageUrl, result);
+	}
+	return results.flatMap((result) => {
+		const rawUrl = result.url.trim();
+		const explicitlySchemed = /^[a-z][a-z\d+.-]*:/iu.test(rawUrl);
+		const externallyHosted = explicitlySchemed && /^https?:/iu.test(rawUrl) || /^[\\/]{2}/u.test(rawUrl);
+		const unsupportedScheme = explicitlySchemed && !/^https?:/iu.test(rawUrl);
+		let sameOriginOrUnknown = !externallyHosted;
+		if (unsupportedScheme) sameOriginOrUnknown = false;
+		if (externallyHosted && baseUrl) try {
+			sameOriginOrUnknown = new URL(result.url, baseUrl).origin === new URL(baseUrl).origin;
+		} catch {
+			sameOriginOrUnknown = false;
+		}
+		const hasSection = Boolean(getSearchResultAnchor(result.url) || result.section);
+		const local = sameOriginOrUnknown ? localByKey.get(getSearchResultKey(result)) ?? (hasSection && !fallbackSectionToLocalPage ? void 0 : localPageResults.get(normalizeUrlRouteKey(result.url))) : void 0;
+		if (!local) return preserveUnmatched?.(result) ? [result] : [];
+		return [{
+			...local,
+			id: result.id,
+			score: result.score ?? local.score
+		}];
+	});
+}
+function shouldPreserveUnmatchedExternalResult(options) {
+	const { result, localPagePaths, baseUrl } = options;
+	const path = normalizeUrlRouteKey(result.url);
+	const rawUrl = result.url.trim();
+	const explicitScheme = rawUrl.match(/^([a-z][a-z\d+.-]*):/iu)?.[1]?.toLowerCase();
+	if (explicitScheme && explicitScheme !== "http" && explicitScheme !== "https") return false;
+	const explicitlyHosted = /^[a-z][a-z\d+.-]*:/iu.test(rawUrl) || /^[\\/]{2}/u.test(rawUrl);
+	const knownLocalPath = localPagePaths.has(path);
+	if (!explicitlyHosted) return !knownLocalPath;
+	if (!baseUrl) return true;
+	try {
+		if (new URL(result.url, baseUrl).origin !== new URL(baseUrl).origin) return true;
+	} catch {
+		return false;
+	}
+	return !knownLocalPath;
+}
+function getPageAudienceSource(page, audience) {
+	return audience === "agent" ? page.agentRawContent ?? page.agentFallbackRawContent ?? page.agentContent ?? page.agentFallbackContent ?? page.rawContent ?? page.content : page.rawContent ?? page.content;
+}
+function getPageAudienceRawContent(page, audience) {
+	return resolveDocsAudienceMdxContent(getPageAudienceSource(page, audience), audience);
+}
+function getPageAudienceSectionContent(page, audience) {
+	const content = getPageAudienceRawContent(page, audience);
+	return audience === "agent" ? upsertPageAgentContractMarkdown(content, page.agent) : content;
+}
+/**
+* Build the exact normalized-input projection represented by a retrieval source digest.
+* This is public so consumers can independently reproduce `source.digest`.
+*/
+function buildDocsRetrievalDigestProjection(page, audience = "human") {
+	const audienceContent = getPageAudienceRawContent(page, audience);
+	return audience === "agent" ? upsertPageAgentContractMarkdown(audienceContent, page.agent) : [audienceContent, renderPageAgentContractMarkdown(page.agent)].filter(Boolean).join("\n\n");
+}
+function getPageAudienceSearchText(page, audience) {
+	return stripMarkdownText(getPageAudienceRawContent(page, audience));
+}
+function getPageAudienceIndexContent(page, audience) {
+	return normalizeWhitespace([getPageAudienceSearchText(page, audience), getPageAgentContractSearchText(page)].join(" "));
+}
+function sortRetrievalSourceValues(values) {
+	const sorted = Array.from(new Set(values)).sort(compareSearchMetadataValues).slice(0, MAX_SEARCH_FILTER_VALUES);
+	return sorted.length > 0 ? sorted : void 0;
+}
+function buildDocsRetrievalSourceScope(page, audience, localeFallback) {
+	const resolved = resolveDocsSearchPageScope(page);
+	const rawLocale = (page.locale ?? localeFallback)?.trim();
+	const locale = rawLocale ? normalizeAgentLocale(rawLocale).slice(0, MAX_SEARCH_FILTER_VALUE_CHARS) : void 0;
+	const framework = sortRetrievalSourceValues(resolved.framework);
+	const version = sortRetrievalSourceValues(resolved.version);
+	const versionGroups = resolved.declarations.version.map((group) => sortRetrievalSourceValues(group)).filter((group) => Boolean(group)).slice(0, MAX_SEARCH_FILTER_VALUES);
+	const packageNames = sortRetrievalSourceValues(resolved.package);
+	const tags = sortRetrievalSourceValues(resolved.tags);
+	const truncated = SEARCH_FILTER_FIELDS.filter((field) => {
+		if (field === "version") return resolved.version.length > MAX_SEARCH_FILTER_VALUES || resolved.declarations.version.length > MAX_SEARCH_FILTER_VALUES || resolved.declarations.version.some((group) => group.length > MAX_SEARCH_FILTER_VALUES);
+		return resolved[field].length > MAX_SEARCH_FILTER_VALUES;
+	});
+	return {
+		audience,
+		...locale ? { locale: [locale] } : {},
+		...framework ? { framework } : {},
+		...version ? { version } : {},
+		...versionGroups.length > 1 ? { versionGroups } : {},
+		...packageNames ? { package: packageNames } : {},
+		...tags ? { tags } : {},
+		...truncated.length > 0 ? { truncated } : {},
+		...resolved.conflicts.length > 0 ? { conflicts: [...resolved.conflicts].sort((left, right) => SEARCH_FILTER_FIELDS.indexOf(left) - SEARCH_FILTER_FIELDS.indexOf(right)) } : {}
+	};
+}
+function buildDocsRetrievalScopeIdentity(page, audience, localeFallback) {
+	const resolved = resolveDocsSearchPageScope(page);
+	const sortValues = (values) => Array.from(new Set(values)).sort(compareSearchMetadataValues);
+	const declarations = Object.fromEntries(SEARCH_FILTER_FIELDS.map((field) => [field, resolved.declarations[field].map(sortValues).sort((left, right) => compareSearchMetadataValues(JSON.stringify(left), JSON.stringify(right)))]));
+	return hashDocsRetrievalValue(JSON.stringify({
+		audience,
+		locale: (page.locale ?? localeFallback)?.trim(),
+		declarations,
+		conflicts: [...resolved.conflicts].sort((left, right) => SEARCH_FILTER_FIELDS.indexOf(left) - SEARCH_FILTER_FIELDS.indexOf(right))
+	}));
+}
+function getUrlHash(value) {
+	const hashIndex = value.indexOf("#");
+	return hashIndex >= 0 ? value.slice(hashIndex) : "";
+}
+function resolveDocsRetrievalCanonicalUrl(page, resultUrl, baseUrl) {
+	const requestedCanonical = page.canonicalUrl?.trim();
+	const requested = requestedCanonical && requestedCanonical.length <= MAX_RETRIEVAL_SOURCE_URL_CHARS ? requestedCanonical : page.url;
+	const explicitScheme = requested.match(/^([a-z][a-z\d+.-]*):/iu)?.[1]?.toLowerCase();
+	const pageScheme = page.url.match(/^([a-z][a-z\d+.-]*):/iu)?.[1]?.toLowerCase();
+	const safePageUrl = pageScheme && pageScheme !== "http" && pageScheme !== "https" ? "/" : page.url;
+	const configured = explicitScheme && explicitScheme !== "http" && explicitScheme !== "https" ? safePageUrl : requested;
+	let canonical = configured;
+	if (baseUrl) try {
+		canonical = new URL(configured, baseUrl).toString();
+	} catch {
+		canonical = configured;
+	}
+	else if (configured.startsWith("//")) canonical = `https:${configured}`;
+	const withSection = `${canonical.split("#", 1)[0]}${getUrlHash(resultUrl)}`;
+	if (withSection.length <= MAX_RETRIEVAL_SOURCE_URL_CHARS && isDocsRetrievalCanonicalUrl(withSection)) return withSection;
+	const fallback = (baseUrl ? (() => {
+		try {
+			return new URL(safePageUrl, baseUrl).toString();
+		} catch {
+			return safePageUrl;
+		}
+	})() : safePageUrl).split("#", 1)[0];
+	if (fallback.length <= MAX_RETRIEVAL_SOURCE_URL_CHARS && isDocsRetrievalCanonicalUrl(fallback)) return fallback;
+	if (baseUrl) try {
+		const root = new URL("/", baseUrl).toString();
+		if (root.length <= MAX_RETRIEVAL_SOURCE_URL_CHARS && isDocsRetrievalCanonicalUrl(root)) return root;
+	} catch {}
+	return "/";
+}
+function hashDocsRetrievalValue(value) {
+	return digestDocsRetrievalContent(value);
+}
+const docsRetrievalDigestMemo = /* @__PURE__ */ new WeakMap();
+function getDocsRetrievalSourceDigest(page, audience, cache) {
+	const cached = cache?.get(page);
+	if (cached) return cached;
+	const source = getPageAudienceSource(page, audience);
+	let agentContractKey = "";
+	let cacheable = true;
+	try {
+		agentContractKey = JSON.stringify(page.agent ?? null);
+	} catch {
+		cacheable = false;
+	}
+	const memo = docsRetrievalDigestMemo.get(page)?.[audience];
+	if (cacheable && memo && memo.source === source && memo.agentContractKey === agentContractKey) {
+		cache?.set(page, memo.digest);
+		return memo.digest;
+	}
+	const digest = hashDocsRetrievalValue(buildDocsRetrievalDigestProjection(page, audience));
+	if (cacheable) {
+		const pageMemo = docsRetrievalDigestMemo.get(page) ?? {};
+		pageMemo[audience] = {
+			source,
+			agentContractKey,
+			digest
+		};
+		docsRetrievalDigestMemo.set(page, pageMemo);
+	}
+	cache?.set(page, digest);
+	return digest;
+}
+function resolveDocsRetrievalLastModified(page, audience) {
+	const parseCandidate = (value) => {
+		const normalized = value?.trim();
+		if (!normalized) return void 0;
+		const timestamp = Date.parse(normalized);
+		return Number.isFinite(timestamp) ? {
+			value: normalized,
+			timestamp
+		} : void 0;
+	};
+	const pageModified = parseCandidate(page.lastmod) ?? parseCandidate(page.lastModified);
+	if (!(audience === "agent" && (page.agentRawContent !== void 0 || page.agentContent !== void 0))) return pageModified?.value;
+	const agentModified = parseCandidate(page.agentLastModified);
+	if (!renderPageAgentContractMarkdown(page.agent)) return agentModified?.value ?? pageModified?.value;
+	if (!agentModified) return pageModified?.value;
+	if (!pageModified) return agentModified.value;
+	return agentModified.timestamp >= pageModified.timestamp ? agentModified.value : pageModified.value;
+}
+async function buildDocsSearchIndexGeneration(pages, options) {
+	const sources = (await Promise.all(pages.map(async (rawPage) => {
+		const page = localizeDocsSearchPage(rawPage, options.locale);
+		const authoredLastModified = page.lastmod?.trim();
+		return {
+			canonicalIdentity: normalizeAuthoredUrlIdentity(page.canonicalUrl?.trim() || page.url),
+			url: normalizeAuthoredUrlIdentity(page.url),
+			indexedUrl: page.url,
+			title: page.title,
+			description: page.description,
+			type: page.type,
+			scope: buildDocsRetrievalSourceScope(page, options.audience, options.locale),
+			scopeIdentity: buildDocsRetrievalScopeIdentity(page, options.audience, options.locale),
+			lastModified: authoredLastModified && Number.isFinite(Date.parse(authoredLastModified)) ? authoredLastModified : void 0,
+			digest: getDocsRetrievalSourceDigest(rawPage, options.audience, options.digestCache),
+			agentContract: getPageAgentContractSearchText(rawPage)
+		};
+	}))).sort((left, right) => {
+		const canonical = compareSearchMetadataValues(left.canonicalIdentity, right.canonicalIdentity);
+		if (canonical !== 0) return canonical;
+		const url = compareSearchMetadataValues(left.url, right.url);
+		if (url !== 0) return url;
+		const digest = compareSearchMetadataValues(left.digest, right.digest);
+		if (digest !== 0) return digest;
+		const title = compareSearchMetadataValues(left.title, right.title);
+		return title !== 0 ? title : compareSearchMetadataValues(JSON.stringify(left), JSON.stringify(right));
+	});
+	return hashDocsRetrievalValue(JSON.stringify({
+		format: RETRIEVAL_INDEX_FORMAT,
+		audience: options.audience,
+		chunking: options.chunking.strategy ?? "section",
+		sources
+	}));
+}
+/**
+* Build a deterministic, body-free inventory for content-change synchronization.
+*
+* Its generation is identical to structured search for the same pages, audience,
+* locale, base URL, and chunking policy.
+*/
+async function buildDocsContentSnapshot(options) {
+	const pages = filterDocsPagesByAccess(options.pages, options.principal);
+	const audience = resolveDocsSearchAudience(options.audience);
+	const search = normalizeDocsSearchConfig(options.search);
+	const digestCache = /* @__PURE__ */ new Map();
+	const indexGeneration = options.indexGeneration ?? await buildDocsSearchIndexGeneration(pages, {
+		audience,
+		chunking: search.chunking,
+		locale: options.locale,
+		baseUrl: options.baseUrl,
+		digestCache
+	});
+	const documents = await Promise.all(pages.map(async (page) => {
+		const localizedPage = localizeDocsSearchPage(page, options.locale);
+		const source = await buildDocsRetrievalSource(page, localizedPage.url, {
+			audience,
+			chunking: search.chunking,
+			locale: options.locale,
+			baseUrl: options.baseUrl,
+			indexGeneration,
+			digestCache
+		});
+		const canonicalUrl = source.canonicalUrl.split("#", 1)[0];
+		return {
+			url: localizedPage.url,
+			canonicalUrl,
+			digest: hashDocsRetrievalValue(JSON.stringify({
+				format: "docs-content-document.v1",
+				url: localizedPage.url,
+				canonicalUrl,
+				title: localizedPage.title,
+				description: localizedPage.description,
+				type: localizedPage.type,
+				scope: source.scope,
+				lastModified: source.lastModified,
+				sourceDigest: source.digest
+			})),
+			...source.lastModified ? { lastModified: source.lastModified } : {}
+		};
+	}));
+	documents.sort((left, right) => {
+		const canonical = compareSearchMetadataValues(left.canonicalUrl, right.canonicalUrl);
+		return canonical !== 0 ? canonical : compareSearchMetadataValues(left.url, right.url);
+	});
+	for (let index = 1; index < documents.length; index += 1) if (documents[index - 1]?.canonicalUrl === documents[index]?.canonicalUrl) throw new DocsSearchRequestError(`Content-change snapshots require unique canonical URLs; duplicate: ${documents[index].canonicalUrl}`);
+	return {
+		format: "docs-content-snapshot.v1",
+		audience,
+		...options.locale ? { locale: normalizeAgentLocale(options.locale) } : {},
+		...options.baseUrl ? { baseUrl: options.baseUrl } : {},
+		indexGeneration,
+		documents
+	};
+}
+async function buildDocsRetrievalSource(rawPage, resultUrl, options) {
+	const page = localizeDocsSearchPage(rawPage, options.locale);
+	const lastModified = resolveDocsRetrievalLastModified(rawPage, options.audience);
+	return {
+		canonicalUrl: resolveDocsRetrievalCanonicalUrl(page, resultUrl, options.baseUrl),
+		scope: buildDocsRetrievalSourceScope(page, options.audience, options.locale),
+		...lastModified ? { lastModified } : {},
+		digest: getDocsRetrievalSourceDigest(rawPage, options.audience, options.digestCache),
+		indexGeneration: options.indexGeneration
+	};
+}
+function parseRetrievalSourceString(value, maxChars = MAX_RETRIEVAL_SOURCE_VALUE_CHARS) {
+	if (typeof value !== "string") return void 0;
+	const normalized = value.trim();
+	if (!normalized || normalized.length > maxChars) return void 0;
+	if (Array.from(normalized).some((character) => {
+		const codePoint = character.codePointAt(0) ?? 0;
+		return codePoint <= 31 || codePoint === 127;
+	})) return void 0;
+	return normalized;
+}
+function parseRetrievalSourceValues(field, value) {
+	if (!Array.isArray(value) || value.length > MAX_SEARCH_FILTER_VALUES) return { valid: false };
+	const parsed = [];
+	for (const item of value) {
+		const stringValue = parseRetrievalSourceString(item, MAX_SEARCH_FILTER_VALUE_CHARS);
+		if (!stringValue) return { valid: false };
+		if (field === "locale") {
+			const normalizedLocale = normalizeAgentLocale(stringValue);
+			if (!normalizedLocale) return { valid: false };
+			parsed.push(normalizedLocale);
+			continue;
+		}
+		const normalized = normalizeDocsSearchFilterValue(field, stringValue);
+		if (!normalized) return { valid: false };
+		parsed.push(normalized);
+	}
+	return {
+		valid: true,
+		values: sortRetrievalSourceValues(parsed)
+	};
+}
+function parseRetrievalSourceVersionGroups(value) {
+	if (!Array.isArray(value) || value.length === 0 || value.length > MAX_SEARCH_FILTER_VALUES) return { valid: false };
+	const groups = value.map((group) => parseRetrievalSourceValues("version", group));
+	if (groups.some((group) => !group.valid || !group.values || group.values.length === 0)) return { valid: false };
+	return {
+		valid: true,
+		groups: groups.map((group) => group.values)
+	};
+}
+function parseDocsRetrievalSource(value, options = {}) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+	const record = value;
+	const canonicalUrl = parseRetrievalSourceString(record.canonicalUrl, MAX_RETRIEVAL_SOURCE_URL_CHARS);
+	const digest = parseRetrievalSourceString(record.digest);
+	const indexGeneration = parseRetrievalSourceString(record.indexGeneration);
+	if (!canonicalUrl || !digest || !indexGeneration) return void 0;
+	const digestPattern = /^sha256:[a-f\d]{64}$/iu;
+	if (!digestPattern.test(digest) || !digestPattern.test(indexGeneration)) return void 0;
+	if (!isDocsRetrievalCanonicalUrl(canonicalUrl) || /^\/(?!\/)/u.test(canonicalUrl) && !options.allowRootRelativeCanonical) return;
+	if (!record.scope || typeof record.scope !== "object" || Array.isArray(record.scope)) return;
+	const rawScope = record.scope;
+	const audience = rawScope.audience === "human" || rawScope.audience === "agent" ? rawScope.audience : void 0;
+	if (!audience) return void 0;
+	const parseScopeFields = (value) => {
+		if (!Array.isArray(value) || value.length > SEARCH_FILTER_FIELDS.length || value.some((field) => typeof field !== "string" || !SEARCH_FILTER_FIELDS.includes(field))) return { valid: false };
+		return {
+			valid: true,
+			values: Array.from(new Set(value)).sort((left, right) => SEARCH_FILTER_FIELDS.indexOf(left) - SEARCH_FILTER_FIELDS.indexOf(right))
+		};
+	};
+	const parseOptionalValues = (field, value) => value === void 0 ? { valid: true } : parseRetrievalSourceValues(field, value);
+	const parseOptionalScopeFields = (value) => value === void 0 ? { valid: true } : parseScopeFields(value);
+	const conflicts = parseOptionalScopeFields(rawScope.conflicts);
+	const truncated = parseOptionalScopeFields(rawScope.truncated);
+	const locale = parseOptionalValues("locale", rawScope.locale);
+	const framework = parseOptionalValues("framework", rawScope.framework);
+	const version = parseOptionalValues("version", rawScope.version);
+	const versionGroups = rawScope.versionGroups === void 0 ? {
+		valid: true,
+		groups: void 0
+	} : parseRetrievalSourceVersionGroups(rawScope.versionGroups);
+	const packageNames = parseOptionalValues("package", rawScope.package);
+	const tags = parseOptionalValues("tags", rawScope.tags);
+	if (!conflicts.valid || !truncated.valid || !locale.valid || !framework.valid || !version.valid || !versionGroups.valid || !packageNames.valid || !tags.valid) return;
+	const scope = {
+		audience,
+		...locale.values ? { locale: locale.values } : {},
+		...framework.values ? { framework: framework.values } : {},
+		...version.values ? { version: version.values } : {},
+		...versionGroups.groups ? { versionGroups: versionGroups.groups } : {},
+		...packageNames.values ? { package: packageNames.values } : {},
+		...tags.values ? { tags: tags.values } : {},
+		...truncated.values && truncated.values.length > 0 ? { truncated: truncated.values } : {},
+		...conflicts.values && conflicts.values.length > 0 ? { conflicts: conflicts.values } : {}
+	};
+	const rawLastModified = parseRetrievalSourceString(record.lastModified);
+	if (record.lastModified !== void 0 && (!rawLastModified || !Number.isFinite(Date.parse(rawLastModified)))) return;
+	const lastModified = rawLastModified && Number.isFinite(Date.parse(rawLastModified)) ? rawLastModified : void 0;
+	return {
+		canonicalUrl,
+		scope,
+		...lastModified ? { lastModified } : {},
+		digest,
+		indexGeneration
+	};
+}
+function docsRetrievalSourceMatchesRequest(source, audience, filters, locale) {
+	if (source.scope.audience !== audience) return false;
+	for (const field of SEARCH_FILTER_FIELDS) {
+		const requested = filters?.[field];
+		if (!requested?.length) continue;
+		if (source.scope.conflicts?.includes(field)) return false;
+		if (source.scope.truncated?.includes(field)) return false;
+		if (field === "version" && source.scope.versionGroups?.length) {
+			if (!agentVersionConstraintGroupsOverlap([requested, ...source.scope.versionGroups])) return false;
+			continue;
+		}
+		const candidates = source.scope[field];
+		if (!candidates?.length) return false;
+		if (!requested.some((requestedValue) => candidates.some((candidate) => docsSearchScopeValueMatches(field, requestedValue, candidate)))) return false;
+	}
+	const requestedLocale = locale ? normalizeAgentLocale(locale) : void 0;
+	if (requestedLocale && (!source.scope.locale?.length || !source.scope.locale.some((candidate) => normalizeAgentLocale(candidate) === requestedLocale))) return false;
+	return true;
+}
+const HOSTED_RETRIEVAL_SOURCE_FIELDS = [
+	"source_canonical_url",
+	"source_scope_audience",
+	"source_scope_locale",
+	"source_scope_framework",
+	"source_scope_version",
+	"source_scope_version_groups",
+	"source_scope_package",
+	"source_scope_tags",
+	"source_scope_truncated",
+	"source_scope_conflicts",
+	"source_last_modified",
+	"source_digest",
+	"source_index_generation"
+];
+function readFlattenedHostedRetrievalSource(record) {
+	return parseDocsRetrievalSource({
+		canonicalUrl: record.source_canonical_url,
+		scope: {
+			audience: record.source_scope_audience,
+			locale: record.source_scope_locale,
+			framework: record.source_scope_framework,
+			version: record.source_scope_version,
+			versionGroups: (() => {
+				const value = record.source_scope_version_groups;
+				if (typeof value !== "string") return value;
+				try {
+					return JSON.parse(value);
+				} catch {
+					return null;
+				}
+			})(),
+			package: record.source_scope_package,
+			tags: record.source_scope_tags,
+			truncated: record.source_scope_truncated,
+			conflicts: record.source_scope_conflicts
+		},
+		lastModified: record.source_last_modified,
+		digest: record.source_digest,
+		indexGeneration: record.source_index_generation
+	}, { allowRootRelativeCanonical: true });
+}
+function readHostedRetrievalSource(record) {
+	const hasNested = record.source !== void 0;
+	const hasFlattened = HOSTED_RETRIEVAL_SOURCE_FIELDS.some((key) => key in record);
+	if (hasNested) {
+		const nested = parseDocsRetrievalSource(record.source, { allowRootRelativeCanonical: true });
+		if (!nested) return void 0;
+		if (!hasFlattened) return nested;
+		const flattened = readFlattenedHostedRetrievalSource(record);
+		return flattened && JSON.stringify(flattened) === JSON.stringify(nested) ? nested : void 0;
+	}
+	return readFlattenedHostedRetrievalSource(record);
+}
+function hasHostedRetrievalSource(record) {
+	return record.source !== void 0 || [
+		"source_corpus_id",
+		"source_document_id",
+		...HOSTED_RETRIEVAL_SOURCE_FIELDS
+	].some((key) => key in record);
+}
+function serializeHostedRetrievalSource(source, corpusId, sourceDocumentId) {
+	if (!source) return {};
+	return {
+		source_corpus_id: corpusId,
+		source_document_id: sourceDocumentId,
+		source_canonical_url: source.canonicalUrl,
+		source_scope_audience: source.scope.audience,
+		source_scope_locale: source.scope.locale,
+		source_scope_framework: source.scope.framework,
+		source_scope_version: source.scope.version,
+		source_scope_version_groups: source.scope.versionGroups ? JSON.stringify(source.scope.versionGroups) : void 0,
+		source_scope_package: source.scope.package,
+		source_scope_tags: source.scope.tags,
+		source_scope_truncated: source.scope.truncated,
+		source_scope_conflicts: source.scope.conflicts,
+		source_last_modified: source.lastModified,
+		source_digest: source.digest,
+		source_index_generation: source.indexGeneration
+	};
+}
+function resolveHostedCorpusId(syncNamespace, context) {
+	const explicitNamespace = syncNamespace?.trim();
+	if (explicitNamespace && explicitNamespace.length > 1024) throw new Error("Search syncNamespace must be 1024 characters or fewer.");
+	let canonicalIdentity;
+	const indexBaseUrl = context.indexBaseUrl;
+	if (!explicitNamespace && indexBaseUrl) try {
+		const url = new URL(indexBaseUrl);
+		if ((url.protocol === "http:" || url.protocol === "https:") && !url.username && !url.password) canonicalIdentity = `${url.origin}${url.pathname.replace(/\/+$/u, "") || "/"}`;
+	} catch {}
+	const identity = explicitNamespace ? `namespace:${explicitNamespace}` : canonicalIdentity ? `canonical:${canonicalIdentity}` : void 0;
+	if (!identity) return void 0;
+	return hashDocsRetrievalValue(JSON.stringify({
+		format: "docs-hosted-corpus.v1",
+		identity,
+		audience: resolveDocsSearchAudience(context.audience),
+		locale: context.locale ? normalizeAgentLocale(context.locale) : "__all__"
+	}));
+}
+function resolveHostedHumanCorpusId(syncNamespace, context) {
+	return resolveHostedCorpusId(syncNamespace, {
+		audience: "human",
+		locale: context.locale,
+		baseUrl: context.baseUrl,
+		indexBaseUrl: context.indexBaseUrl
+	});
+}
+function makeHostedProviderDocumentId(corpusId, sourceDocumentId) {
+	return `docs_${hashDocsRetrievalValue(JSON.stringify({
+		format: "docs-hosted-document.v1",
+		corpusId,
+		sourceDocumentId
+	})).slice(7)}`;
+}
+function readHostedSourceDocumentId(record) {
+	return parseRetrievalSourceString(record.source_document_id, MAX_RETRIEVAL_SOURCE_URL_CHARS);
+}
+function hostedRecordMatchesCorpus(record, corpusId) {
+	if (!corpusId) return true;
+	if (record.source_corpus_id === corpusId) return true;
+	return record.source_corpus_id === void 0 && !hasHostedRetrievalSource(record);
+}
+async function enrichDocsSearchResultsWithSources(options) {
+	const digestCache = /* @__PURE__ */ new Map();
+	const localizedPages = options.pages.map((page) => localizeDocsSearchPage(page, options.locale));
+	const pagesByRoute = /* @__PURE__ */ new Map();
+	for (const page of localizedPages) {
+		const route = normalizeUrlRouteKey(page.url);
+		if (!pagesByRoute.has(route)) pagesByRoute.set(route, page);
+	}
+	let resolvedIndexGeneration;
+	const getIndexGeneration = () => {
+		resolvedIndexGeneration ??= options.indexGeneration ? Promise.resolve(options.indexGeneration) : buildDocsSearchIndexGeneration(options.generationPages ?? options.pages, {
+			audience: options.audience,
+			chunking: options.chunking,
+			locale: options.locale,
+			baseUrl: options.baseUrl,
+			digestCache
+		});
+		return resolvedIndexGeneration;
+	};
+	return (await Promise.all(options.results.map(async (result) => {
+		const { source: rawSource, ...resultWithoutSource } = result;
+		const page = findPageForSearchResult(localizedPages, result, options.baseUrl, pagesByRoute);
+		if (page) return {
+			...resultWithoutSource,
+			trust: resolveDocsOkfTrustMetadata(page),
+			source: await buildDocsRetrievalSource(page, result.url, {
+				audience: options.audience,
+				chunking: options.chunking,
+				locale: options.locale,
+				baseUrl: options.baseUrl,
+				indexGeneration: await getIndexGeneration(),
+				digestCache
+			})
+		};
+		if (rawSource === void 0) return resultWithoutSource;
+		const source = parseDocsRetrievalSource(rawSource, { allowRootRelativeCanonical: options.requireCurrentIndexGeneration });
+		if (!source) return null;
+		if (!docsRetrievalSourceMatchesRequest(source, options.audience, options.filters, options.locale)) return null;
+		if (options.requireCurrentIndexGeneration && source.indexGeneration !== await getIndexGeneration()) return null;
+		return {
+			...resultWithoutSource,
+			source
+		};
+	}))).filter((result) => Boolean(result));
+}
+async function enrichDocsSearchDocumentsWithSources(options) {
+	const results = await enrichDocsSearchResultsWithSources({
+		results: options.documents.map((document) => ({
+			id: document.id,
+			url: document.url,
+			content: document.title,
+			description: document.description,
+			type: document.type,
+			section: document.section,
+			source: document.source
+		})),
+		pages: options.pages,
+		audience: options.audience,
+		chunking: options.chunking,
+		locale: options.locale,
+		baseUrl: options.baseUrl,
+		indexGeneration: options.indexGeneration
+	});
+	const sources = new Map(results.map((result) => [result.id, result.source]));
+	return options.documents.map((document) => {
+		const source = sources.get(document.id);
+		return source ? {
+			...document,
+			source
+		} : document;
+	});
+}
+/**
+* Attach the same canonical provenance used by built-in search providers.
+* Custom adapters can call this before persisting their own hosted records.
+*/
+function enrichDocsSearchDocumentsWithProvenance(options) {
+	return enrichDocsSearchDocumentsWithSources({
+		...options,
+		audience: resolveDocsSearchAudience(options.audience),
+		chunking: options.chunking ?? { strategy: "section" }
+	});
+}
+function isLocalProviderResult(result, baseUrl) {
+	const rawUrl = result.url.trim();
+	const explicitScheme = rawUrl.match(/^([a-z][a-z\d+.-]*):/iu)?.[1]?.toLowerCase();
+	if (explicitScheme && explicitScheme !== "http" && explicitScheme !== "https") return false;
+	if (!(/^[a-z][a-z\d+.-]*:/iu.test(rawUrl) || /^[\\/]{2}/u.test(rawUrl))) return true;
+	if (!baseUrl) return false;
+	try {
+		return new URL(result.url, baseUrl).origin === new URL(baseUrl).origin;
+	} catch {
+		return false;
+	}
+}
+function hasOppositeAudienceEvidence(options) {
+	const { result, pages, query, audience, baseUrl } = options;
+	if (!isLocalProviderResult(result, baseUrl)) return false;
+	const pagePath = normalizeUrlRouteKey(result.url);
+	const page = pages.find((candidate) => normalizeUrlRouteKey(candidate.url) === pagePath);
+	if (!page) return false;
+	if (scoreDocument(query, pageToSearchDocument(page, audience)) > 0) return false;
+	const oppositeAudience = audience === "agent" ? "human" : "agent";
+	if (scoreDocument(query, pageToSearchDocument(page, oppositeAudience)) > 0) return true;
+	const evidence = cleanSearchResultText(result.description);
+	if (!evidence) return false;
+	const selectedTokens = new Set(tokenizeSearchQuery(getPageAudienceSearchText(page, audience)));
+	const oppositeTokens = new Set(tokenizeSearchQuery(getPageAudienceSearchText(page, oppositeAudience)));
+	const evidenceTokens = [...new Set(tokenizeSearchQuery(evidence))];
+	let selectedOnlyMatches = 0;
+	let oppositeOnlyMatches = 0;
+	for (const token of evidenceTokens) {
+		const inSelected = selectedTokens.has(token);
+		const inOpposite = oppositeTokens.has(token);
+		if (inSelected && !inOpposite) selectedOnlyMatches += 1;
+		if (inOpposite && !inSelected) oppositeOnlyMatches += 1;
+	}
+	return oppositeOnlyMatches > selectedOnlyMatches;
+}
+function pageToSearchDocument(rawPage, audience = "human") {
+	const page = localizeDocsSearchPage(rawPage, rawPage.locale);
+	const scope = resolveDocsSearchPageScope(page);
+	return {
+		id: makeDocumentId(page.url, "page"),
+		url: page.url,
+		title: page.title,
+		content: getPageAudienceIndexContent(page, audience),
+		description: page.description,
+		type: "page",
+		locale: page.locale,
+		framework: scope.framework[0],
+		version: scope.version[0],
+		package: scope.package.length > 0 ? scope.package : void 0,
+		tags: scope.tags.length > 0 ? scope.tags : void 0
+	};
+}
+function buildExactPageSearchResults(query, pages, audience = "human") {
+	const normalizedQuery = normalizeSearchPhrase(query);
+	if (!normalizedQuery) return [];
+	const results = [];
+	for (const page of pages) {
+		const document = pageToSearchDocument(page, audience);
+		const title = normalizeSearchPhrase(page.title);
+		const urlSegments = getUrlSearchSegments(page.url);
+		if (!(title === normalizedQuery || urlSegments.includes(normalizedQuery))) continue;
+		results.push({
+			id: document.id,
+			url: document.url,
+			content: cleanSearchResultText(document.title) ?? document.title,
+			description: cleanSearchResultText(buildSnippet(document, query) ?? document.description),
+			type: "page",
+			score: scoreDocument(query, document) + 2e3
+		});
+	}
+	return results.sort((a, b) => (b.score ?? 0) - (a.score ?? 0) || a.url.localeCompare(b.url));
+}
+function hasDistinctResultSection(result) {
+	if (result.type === "page") return false;
+	const section = normalizeSearchPhrase(stripHtml(result.section ?? ""));
+	if (!section) return true;
+	return section !== normalizeSearchPhrase(normalizeSearchPhrase(stripHtml(result.content)).split(/\s+[—–]\s+/)[0] ?? "");
+}
+function insideLiteralResultPriority(query, result) {
+	if (!hasDistinctResultSection(result) || !isLiteralLookupQuery(query)) return 0;
+	return Math.max(literalMatchPriority(query, stripHtml(result.section ?? "")), literalMatchPriority(query, stripHtml(result.description ?? "")));
+}
+function prioritizeLiteralInsideResults(query, results) {
+	if (!isLiteralLookupQuery(query)) return results;
+	return [...results].sort((a, b) => {
+		const literalDelta = insideLiteralResultPriority(query, b) - insideLiteralResultPriority(query, a);
+		if (literalDelta) return literalDelta;
+		return 0;
+	});
+}
+function rankAskAIContextResult(query, result) {
+	return scoreDocument(query, {
+		id: result.id,
+		url: result.url,
+		title: result.title,
+		content: result.contextContent,
+		description: result.description,
+		type: result.type,
+		section: result.section
+	});
+}
+function buildAskAIContextBlock(result) {
+	const lines = [`## ${result.title}`, `URL: ${result.url}`];
+	if (result.section) lines.push(`Section: ${result.section}`);
+	if (result.description) lines.push(`Search snippet: ${result.description}`);
+	if (result.source) {
+		const scope = result.source.scope;
+		const scopeEntries = [
+			`audience=${scope.audience}`,
+			scope.locale?.length ? `locale=${scope.locale.join(",")}` : void 0,
+			scope.framework?.length ? `framework=${scope.framework.join(",")}` : void 0,
+			scope.version?.length ? `version=${scope.version.join(",")}` : void 0,
+			scope.package?.length ? `package=${scope.package.join(",")}` : void 0,
+			scope.tags?.length ? `tags=${scope.tags.join(",")}` : void 0,
+			scope.conflicts?.length ? `conflicts=${scope.conflicts.join(",")}` : void 0
+		].filter((value) => Boolean(value));
+		lines.push(`Canonical URL: ${result.source.canonicalUrl}`);
+		lines.push(`Source scope: ${scopeEntries.join("; ")}`);
+		if (result.source.lastModified) lines.push(`Source modified: ${result.source.lastModified}`);
+		lines.push(`Source digest: ${result.source.digest}`);
+		lines.push(`Index generation: ${result.source.indexGeneration}`);
+	}
+	lines.push("", result.contextContent);
+	return lines.join("\n").trim();
+}
+function makeDocumentId(url, suffix) {
+	return `${url}#${suffix}`;
+}
+function splitPageIntoSections(page, audience = "human") {
+	const raw = getPageAudienceSectionContent(page, audience);
+	const generatedContract = audience === "agent" ? findDocsGeneratedAgentContractRanges(raw)[0] : void 0;
+	const scope = resolveDocsSearchPageScope(page);
+	let documentIndex = 0;
+	return parseDocsMarkdownSections(raw).flatMap((section) => {
+		if (generatedContract && section.startLine > generatedContract.startLine && section.startLine < generatedContract.endLine) return [];
+		const content = normalizeWhitespace(stripMarkdownText(section.content));
+		if (!content) return [];
+		const index = documentIndex;
+		documentIndex += 1;
+		return [{
+			id: makeDocumentId(page.url, `section-${index}`),
+			url: `${page.url.split("#", 1)[0]}#${encodeURIComponent(section.anchor)}`,
+			title: page.title,
+			section: section.title,
+			content,
+			description: page.description,
+			type: "heading",
+			locale: page.locale,
+			framework: scope.framework[0],
+			version: scope.version[0],
+			package: scope.package.length > 0 ? scope.package : void 0,
+			tags: scope.tags.length > 0 ? scope.tags : void 0
+		}];
+	});
+}
+function buildDocsSearchDocuments(pages, chunking = {}, audience = "human") {
+	const strategy = chunking.strategy ?? "section";
+	return pages.flatMap((rawPage) => {
+		const page = localizeDocsSearchPage(rawPage, rawPage.locale);
+		const base = pageToSearchDocument(page, audience);
+		if (strategy === "page") return [base];
+		const sections = splitPageIntoSections(page, audience);
+		if (sections.length === 0) return [base];
+		return [...base.content ? [base] : [], ...sections];
+	});
+}
+function analyzeDocsSearchDocument(query, document, explain = false) {
+	const q = normalizeSearchPhrase(query);
+	if (!q) return {
+		score: 0,
+		matchedTerms: [],
+		matchedTermsTruncated: false,
+		rankingReasons: []
+	};
+	const words = tokenizeSearchQuery(q);
+	const title = normalizeSearchPhrase(document.title);
+	const section = document.section ? normalizeSearchPhrase(document.section) : "";
+	const hasDistinctSection = Boolean(section && section !== title);
+	const titleSection = section ? normalizeSearchPhrase(`${document.title} ${document.section}`) : "";
+	const description = document.description ? normalizeSearchPhrase(document.description) : "";
+	const content = normalizeSearchPhrase(document.content);
+	const url = normalizeSearchPhrase(document.url);
+	const urlSegments = getUrlSearchSegments(document.url);
+	const titleTokens = tokenizeSearchQuery(title);
+	const sectionTokens = tokenizeSearchQuery(section);
+	let score = 0;
+	const reasonContributions = explain ? /* @__PURE__ */ new Map() : void 0;
+	const addScore = (contribution, code, description) => {
+		score += contribution;
+		if (!reasonContributions) return;
+		const current = reasonContributions.get(code);
+		reasonContributions.set(code, {
+			contribution: (current?.contribution ?? 0) + contribution,
+			description: current?.description ?? description
+		});
+	};
+	const insideLiteralPriority = document.type !== "page" && hasDistinctSection && isLiteralLookupQuery(q) ? Math.max(literalMatchPriority(q, section), literalMatchPriority(q, description), literalMatchPriority(q, content)) : 0;
+	if (insideLiteralPriority > 0) addScore(insideLiteralPriority * 2250, "literal_match", "A short literal lookup matched this section or its searchable text.");
+	if (title === q) addScore(1120, "title_phrase", "The normalized query exactly matches the page title.");
+	else if (title.startsWith(q)) addScore(70, "title_phrase", "The page title starts with the normalized query.");
+	else if (title.includes(q)) addScore(45, "title_phrase", "The page title contains the normalized query.");
+	if (hasDistinctSection) {
+		if (section === q) addScore(1080, "section_phrase", "The normalized query exactly matches the section title.");
+		else if (section.startsWith(q)) addScore(55, "section_phrase", "The section title starts with the normalized query.");
+		else if (section.includes(q)) addScore(30, "section_phrase", "The section title contains the normalized query.");
+		if (titleSection === q) addScore(1e3, "title_section_phrase", "The normalized query exactly matches the combined page and section title.");
+		else if (titleSection.startsWith(q)) addScore(50, "title_section_phrase", "The combined page and section title starts with the normalized query.");
+		else if (titleSection.includes(q)) addScore(28, "title_section_phrase", "The combined page and section title contains the normalized query.");
+	}
+	if (urlSegments.includes(q)) addScore(950, "url_phrase", "The normalized query exactly matches a URL segment.");
+	if (url.includes(q)) addScore(12, "url_phrase", "The result URL contains the normalized query.");
+	if (description.includes(q)) addScore(18, "description_phrase", "The page description contains the normalized query.");
+	if (content.includes(q)) addScore(12, "content_phrase", "The searchable content contains the normalized query.");
+	let matchedWords = 0;
+	for (const word of words) {
+		let matched = false;
+		if (title === word) {
+			addScore(28, "title_terms", "Normalized query terms match the page title.");
+			matched = true;
+		} else if (title.startsWith(word)) {
+			addScore(20, "title_terms", "Normalized query terms match the page title.");
+			matched = true;
+		} else if (title.includes(word)) {
+			addScore(12, "title_terms", "Normalized query terms match the page title.");
+			matched = true;
+		}
+		if (hasDistinctSection) {
+			if (section === word) {
+				addScore(22, "section_terms", "Normalized query terms match the section title.");
+				matched = true;
+			} else if (section.startsWith(word)) {
+				addScore(16, "section_terms", "Normalized query terms match the section title.");
+				matched = true;
+			} else if (section.includes(word)) {
+				addScore(10, "section_terms", "Normalized query terms match the section title.");
+				matched = true;
+			}
+		}
+		if (description.includes(word)) {
+			addScore(6, "description_terms", "Normalized query terms match the page description.");
+			matched = true;
+		}
+		if (content.includes(word)) {
+			addScore(4, "content_terms", "Normalized query terms match the searchable content.");
+			matched = true;
+		}
+		if (matched) matchedWords += 1;
+	}
+	if (words.length > 1) {
+		if (hasDistinctSection && sectionTokens.length > 0 && words.every((word) => sectionTokens.includes(word))) addScore(30, "all_terms_in_section", "Every normalized query term occurs in the section title.");
+		if (document.type === "page" && titleTokens.length > 0 && words.every((word) => titleTokens.includes(word))) addScore(24, "all_terms_in_title", "Every normalized query term occurs in the page title.");
+	}
+	if (matchedWords === words.length && words.length > 1) addScore(20, "all_query_terms", "Every normalized query term matched a searchable field.");
+	if (score > 0 && document.type === "heading" && hasDistinctSection) addScore(6, "heading_boost", "A distinct matching section is preferred over a page-only hit.");
+	const matchedTerms = [];
+	let matchedTermCount = 0;
+	let matchedTermCharactersTruncated = false;
+	if (explain) {
+		const candidateTerms = words.length > 0 ? words : [q];
+		const fields = [
+			["title", title],
+			["section", section],
+			["description", description],
+			["content", content],
+			["url", url]
+		];
+		for (const term of candidateTerms) {
+			const matchingFields = fields.flatMap(([field, value]) => value.includes(term) ? [field] : []);
+			if (matchingFields.length === 0) continue;
+			matchedTermCount += 1;
+			if (matchedTerms.length < MAX_SEARCH_EXPLANATION_TERMS) {
+				matchedTermCharactersTruncated ||= term.length > MAX_SEARCH_EXPLANATION_TERM_CHARS;
+				matchedTerms.push({
+					term: term.slice(0, MAX_SEARCH_EXPLANATION_TERM_CHARS),
+					fields: matchingFields
+				});
+			}
+		}
+	}
+	return {
+		score,
+		matchedTerms,
+		matchedTermsTruncated: matchedTermCount > matchedTerms.length || matchedTermCharactersTruncated,
+		rankingReasons: reasonContributions ? [...reasonContributions.entries()].map(([code, value]) => ({
+			code,
+			...value
+		})).sort((left, right) => right.contribution - left.contribution || left.code.localeCompare(right.code)) : []
+	};
+}
+function scoreDocument(query, document) {
+	return analyzeDocsSearchDocument(query, document).score;
+}
+function getDocsSearchExplanationResultIdentity(result) {
+	return JSON.stringify([
+		result.id,
+		result.url,
+		result.section ?? null
+	]);
+}
+function getDocsSearchExplanationDocumentIdentity(document) {
+	return getSearchResultKey({
+		id: document.id,
+		url: document.url,
+		content: document.title,
+		type: document.type,
+		section: document.section
+	});
+}
+function resolveDocsSearchExplanationDocument(result, documentsById, documentsByResultKey) {
+	const local = documentsById.get(result.id) ?? documentsByResultKey.get(getSearchResultKey(result));
+	if (local) return local;
+	return {
+		id: result.id,
+		url: result.url,
+		title: inferResultTitle(result),
+		content: result.content,
+		description: result.description,
+		section: result.section,
+		type: result.type
+	};
+}
+function buildDocsSearchFilterDecisions(filters, scope) {
+	return SEARCH_FILTER_FIELDS.map((field) => {
+		const requestedValues = filters[field] ?? [];
+		const selectedValues = scope?.[field] ?? [];
+		if (requestedValues.length === 0) return {
+			field,
+			requestedValues: [],
+			selectedValues: [...selectedValues],
+			matchedValues: [],
+			outcome: "not_requested"
+		};
+		const matchedValues = requestedValues.filter((requested) => selectedValues.some((selected) => docsSearchScopeValueMatches(field, requested, selected)));
+		const versionGroupsMatch = field !== "version" || !scope?.versionGroups?.length || agentVersionConstraintGroupsOverlap([requestedValues, ...scope.versionGroups]);
+		const verifiable = Boolean(scope) && !scope?.conflicts?.includes(field) && !scope?.truncated?.includes(field) && selectedValues.length > 0;
+		return {
+			field,
+			requestedValues: [...requestedValues],
+			selectedValues: [...selectedValues],
+			matchedValues,
+			outcome: verifiable && matchedValues.length > 0 && versionGroupsMatch ? "matched" : "not_verifiable"
+		};
+	});
+}
+function buildDocsSearchAmbiguityResolution(filters, scope, warnings, unverifiableFields) {
+	const decisions = SEARCH_AMBIGUITY_FIELDS.map((field) => {
+		const selectedValues = [...scope?.[field] ?? []];
+		const requestedValues = filters[field];
+		if (requestedValues?.length) return {
+			field,
+			status: "resolved_by_filter",
+			selectedValues,
+			candidateValues: [...requestedValues],
+			reason: `The explicit ${field} filter constrained the result set.`
+		};
+		const warning = warnings.find((candidate) => candidate.code === "ambiguous_scope" && candidate.field === field);
+		if (warning) return {
+			field,
+			status: "requires_filter",
+			selectedValues,
+			...warning.values ? { candidateValues: [...warning.values] } : {},
+			reason: `Results span multiple ${field} scopes; select a ${field} filter before acting on scope-specific guidance.`
+		};
+		const hasConflictingMetadata = warnings.some((candidate) => candidate.code === "conflicting_scope_metadata" && candidate.field === field);
+		if (selectedValues.length === 0 || unverifiableFields.has(field) || hasConflictingMetadata) return {
+			field,
+			status: "not_verifiable",
+			selectedValues,
+			reason: `No trusted ${field} scope is available for this result.`
+		};
+		return {
+			field,
+			status: "unambiguous",
+			selectedValues,
+			reason: `The matching result set does not contain conflicting ${field} choices.`
+		};
+	});
+	const hasUnresolved = decisions.some((decision) => decision.status === "requires_filter");
+	const isNotVerifiable = decisions.some((decision) => decision.status === "not_verifiable");
+	const hasResolved = decisions.some((decision) => decision.status === "resolved_by_filter");
+	return {
+		status: hasUnresolved ? "unresolved" : isNotVerifiable ? "not_verifiable" : hasResolved ? "resolved" : "unambiguous",
+		decisions
+	};
+}
+function explainDocsSearchResults(options) {
+	const documentsById = new Map(options.documents.map((document) => [document.id, document]));
+	const documentsByResultKey = new Map(options.documents.map((document) => [getDocsSearchExplanationDocumentIdentity(document), document]));
+	return options.results.map((result, index, results) => {
+		const document = resolveDocsSearchExplanationDocument(result, documentsById, documentsByResultKey);
+		const analysis = analyzeDocsSearchDocument(options.query, document, true);
+		const rankingStrategy = options.resolveRankingStrategy(result);
+		const rankingReasons = rankingStrategy === "provider" ? [{
+			code: "provider_order",
+			description: `The ${options.provider} search adapter supplied this result order; provider-internal ranking details are not available to the shared pipeline.`
+		}] : [...analysis.rankingReasons];
+		if (rankingStrategy === "exact") rankingReasons.unshift({
+			code: "exact_page_boost",
+			contribution: 2e3,
+			description: "An exact normalized page-title or URL-segment match was promoted."
+		});
+		if (rankingStrategy === "provider" && insideLiteralResultPriority(options.query, result) > 0) rankingReasons.push({
+			code: "literal_result_priority",
+			description: "The shared pipeline promoted this distinct section because it matched a short literal lookup."
+		});
+		const resultScore = result.score;
+		const previousScore = index > 0 ? results[index - 1]?.score : void 0;
+		const nextScore = index + 1 < results.length ? results[index + 1]?.score : void 0;
+		if (rankingStrategy !== "provider" && resultScore !== void 0 && (resultScore === previousScore || resultScore === nextScore)) rankingReasons.push({
+			code: "stable_url_tiebreak",
+			description: "A stable URL comparison resolved an equal lexical score."
+		});
+		const selectedScope = result.source?.scope;
+		return {
+			...result,
+			explanation: {
+				format: "docs-search-explanation.v1",
+				rank: options.rankOffset + index + 1,
+				rankingStrategy,
+				matchedTerms: analysis.matchedTerms,
+				matchedTermsTruncated: analysis.matchedTermsTruncated,
+				selectedScope: selectedScope ? { ...selectedScope } : null,
+				filterDecisions: buildDocsSearchFilterDecisions(options.filters, selectedScope),
+				ambiguityResolution: buildDocsSearchAmbiguityResolution(options.filters, selectedScope, options.warnings, options.unverifiableAmbiguityFields),
+				rankingReasons
+			}
+		};
+	});
+}
+function buildSnippet(document, query) {
+	const q = query.trim().toLowerCase();
+	const sources = [normalizeWhitespace(stripMarkdownText(document.content)), normalizeWhitespace(stripMarkdownText(document.description ?? ""))].filter(Boolean);
+	for (const source of sources) {
+		if (!q) return clampSearchSnippet(source);
+		const idx = source.toLowerCase().indexOf(q);
+		if (idx === -1) continue;
+		const start = Math.max(0, idx - 48);
+		const end = Math.min(source.length, idx + q.length + 96);
+		const prefix = start > 0 ? "..." : "";
+		const suffix = end < source.length ? "..." : "";
+		return clampSearchSnippet(`${prefix}${source.slice(start, end).trim()}${suffix}`);
+	}
+	return sources[0] ? clampSearchSnippet(sources[0]) : void 0;
+}
+function clampSearchSnippet(value) {
+	if (value.length <= MAX_SEARCH_SNIPPET_CHARS) return value;
+	return `${value.slice(0, MAX_SEARCH_SNIPPET_CHARS - 3).trimEnd()}...`;
+}
+function cleanSearchResultText(value) {
+	if (!value) return void 0;
+	return normalizeWhitespace(stripHtml(stripMarkdownText(value))) || void 0;
+}
+function getHostedIndexGenerationTag(indexGeneration) {
+	return `docs-generation:${indexGeneration}`;
+}
+function buildAlgoliaRecord(document, corpusId) {
+	const providerDocumentId = corpusId ? makeHostedProviderDocumentId(corpusId, document.id) : document.id;
+	const generationTag = document.source?.indexGeneration ? getHostedIndexGenerationTag(document.source.indexGeneration) : void 0;
+	const record = {
+		objectID: providerDocumentId,
+		id: providerDocumentId,
+		url: document.url,
+		title: document.title,
+		section: document.section,
+		content: document.content,
+		description: document.description,
+		type: document.type,
+		locale: document.locale ?? document.source?.scope.locale?.[0],
+		framework: document.framework,
+		version: document.version,
+		package: document.package,
+		tags: document.tags,
+		_tags: corpusId || generationTag ? [corpusId, generationTag].filter((value) => Boolean(value)) : void 0,
+		...serializeHostedRetrievalSource(document.source, corpusId, document.id)
+	};
+	const encoder = new TextEncoder();
+	const sizeOf = (value) => encoder.encode(JSON.stringify(value)).length;
+	if (sizeOf(record) <= ALGOLIA_MAX_RECORD_BYTES) return record;
+	delete record.description;
+	if (sizeOf(record) <= ALGOLIA_MAX_RECORD_BYTES) return record;
+	record.content = "";
+	for (const field of [
+		"package",
+		"tags",
+		"framework",
+		"version"
+	]) {
+		if (sizeOf(record) <= ALGOLIA_MAX_RECORD_BYTES) break;
+		delete record[field];
+	}
+	const trimFieldToFit = (field, value) => {
+		let low = 0;
+		let high = value.length;
+		let best = "";
+		while (low <= high) {
+			const middle = Math.floor((low + high) / 2);
+			const candidate = middle < value.length ? `${value.slice(0, middle).trimEnd()}...` : value;
+			record[field] = candidate;
+			if (sizeOf(record) <= ALGOLIA_MAX_RECORD_BYTES) {
+				best = candidate;
+				low = middle + 1;
+			} else high = middle - 1;
+		}
+		record[field] = best;
+	};
+	if (sizeOf(record) > ALGOLIA_MAX_RECORD_BYTES && typeof record.section === "string") trimFieldToFit("section", record.section);
+	if (sizeOf(record) > ALGOLIA_MAX_RECORD_BYTES && typeof record.title === "string") trimFieldToFit("title", record.title);
+	if (sizeOf(record) > ALGOLIA_MAX_RECORD_BYTES) throw new Error(`Algolia record ${document.id} exceeds the record limit with required provenance.`);
+	trimFieldToFit("content", document.content);
+	if (sizeOf(record) > ALGOLIA_MAX_RECORD_BYTES) throw new Error(`Algolia record ${document.id} still exceeds the record limit after trimming.`);
+	return record;
+}
+async function searchSimpleDocsPage(query, context) {
+	const limit = query.limit ?? DEFAULT_SEARCH_LIMIT;
+	const offset = query.offset ?? 0;
+	const matches = context.documents.map((document) => ({
+		document,
+		score: scoreDocument(query.query, document)
+	})).filter((item) => item.score > 0).sort((a, b) => {
+		if (b.score !== a.score) return b.score - a.score;
+		return a.document.url.localeCompare(b.document.url);
+	});
+	const results = matches.slice(offset, offset + limit).map(({ document, score }) => ({
+		id: document.id,
+		url: document.url,
+		content: cleanSearchResultText(document.section ? `${document.title} — ${document.section}` : document.title) ?? (document.section ? `${document.title} — ${document.section}` : document.title),
+		description: cleanSearchResultText(buildSnippet(document, query.query) ?? document.description),
+		type: document.type,
+		score,
+		section: document.section,
+		source: document.source
+	}));
+	return {
+		results: context.deferSourceProvenance ? results : await enrichDocsSearchResultsWithSources({
+			results,
+			pages: context.pages,
+			audience: resolveDocsSearchAudience(context.audience),
+			chunking: context.chunking ?? { strategy: "section" },
+			locale: query.locale ?? context.locale,
+			baseUrl: context.baseUrl,
+			indexGeneration: context.indexGeneration,
+			filters: query.filters
+		}),
+		total: matches.length
+	};
+}
+function createSimpleSearchAdapter() {
+	return {
+		name: "simple",
+		async search(query, context) {
+			return (await searchSimpleDocsPage({
+				...query,
+				offset: 0
+			}, context)).results;
+		},
+		searchPage: searchSimpleDocsPage
+	};
+}
+function normalizeDocsSearchConfig(search) {
+	if (search === false) return {
+		enabled: false,
+		provider: "simple",
+		maxResults: DEFAULT_SEARCH_LIMIT,
+		chunking: { strategy: "section" }
+	};
+	if (!search || search === true) return {
+		enabled: true,
+		provider: "simple",
+		maxResults: DEFAULT_SEARCH_LIMIT,
+		chunking: { strategy: "section" },
+		raw: typeof search === "object" ? search : void 0
+	};
+	const provider = search.provider ?? "simple";
+	const maxResults = search.maxResults ?? DEFAULT_SEARCH_LIMIT;
+	const chunking = search.chunking ?? { strategy: "section" };
+	return {
+		enabled: search.enabled ?? true,
+		provider,
+		maxResults,
+		chunking,
+		raw: search
+	};
+}
+function getDocsSearchPaginationProviderIdentity(search) {
+	const raw = search.raw;
+	if (raw?.provider === "algolia") return {
+		provider: "algolia",
+		appId: raw.appId,
+		indexName: raw.indexName,
+		syncNamespace: raw.syncNamespace?.trim() || void 0
+	};
+	if (raw?.provider === "typesense") return {
+		provider: "typesense",
+		baseUrl: raw.baseUrl,
+		collection: raw.collection,
+		mode: raw.mode ?? "keyword",
+		queryBy: raw.queryBy ?? [
+			"title",
+			"section",
+			"content",
+			"description"
+		],
+		embeddings: raw.embeddings ? {
+			provider: raw.embeddings.provider,
+			model: raw.embeddings.model,
+			baseUrl: raw.embeddings.baseUrl ?? "http://127.0.0.1:11434"
+		} : void 0,
+		syncNamespace: raw.syncNamespace?.trim() || void 0
+	};
+	if (raw?.provider === "mcp") return {
+		provider: "mcp",
+		endpoint: raw.endpoint,
+		toolName: raw.toolName ?? "search_docs",
+		protocolVersion: raw.protocolVersion ?? DEFAULT_MCP_PROTOCOL_VERSION,
+		forwardAudience: raw.forwardAudience === true
+	};
+	if (raw?.provider === "custom") return {
+		provider: "custom",
+		adapterName: typeof raw.adapter === "object" && raw.adapter ? raw.adapter.name : void 0,
+		paginationRevision: raw.paginationRevision?.trim() || void 0
+	};
+	return { provider: search.provider };
+}
+async function readResponseJson(response) {
+	const text = await response.text();
+	return text ? JSON.parse(text) : null;
+}
+async function readMcpResponsePayload(response) {
+	const text = await response.text();
+	if (!text) return null;
+	if ((response.headers.get("content-type") ?? "").includes("application/json")) return JSON.parse(text);
+	return normalizeMcpSsePayload(text);
+}
+var DocsSearchHttpError = class extends Error {
+	status;
+	constructor(response, message) {
+		super(`${message} (${response.status} ${response.statusText})`);
+		this.name = "DocsSearchHttpError";
+		this.status = response.status;
+	}
+};
+function ensureOk(response, message) {
+	if (response.ok) return;
+	throw new DocsSearchHttpError(response, message);
+}
+function ensureJsonRpcOk(payload, message) {
+	if (payload && typeof payload === "object" && "error" in payload && payload.error && typeof payload.error === "object" && "message" in payload.error) throw new Error(`${message}: ${String(payload.error.message)}`);
+}
+function resolveMcpEndpoint(endpoint) {
+	if (/^https?:\/\//i.test(endpoint)) return endpoint;
+	throw new Error("Relative MCP search endpoints must be resolved before creating the MCP adapter.");
+}
+function isDocsSearchResultType(value) {
+	return value === "page" || value === "heading" || value === "text";
+}
+function mapMcpSearchResult(value, sourceBaseUrl) {
+	if (!value || typeof value !== "object") return null;
+	const item = value;
+	const section = typeof item.section === "string" ? item.section : void 0;
+	const title = typeof item.title === "string" ? item.title : void 0;
+	const content = typeof item.content === "string" ? item.content : title ? section ? `${title} — ${section}` : title : void 0;
+	const url = typeof item.url === "string" ? item.url : void 0;
+	if (!content || !url) return null;
+	const hasSource = item.source !== void 0;
+	let sourceValue = item.source;
+	if (hasSource && sourceBaseUrl && sourceValue && typeof sourceValue === "object" && !Array.isArray(sourceValue)) {
+		const sourceRecord = sourceValue;
+		if (typeof sourceRecord.canonicalUrl === "string" && /^\/(?!\/)/u.test(sourceRecord.canonicalUrl)) try {
+			sourceValue = {
+				...sourceRecord,
+				canonicalUrl: new URL(sourceRecord.canonicalUrl, sourceBaseUrl).toString()
+			};
+		} catch {}
+	}
+	const source = hasSource ? parseDocsRetrievalSource(sourceValue) : void 0;
+	if (hasSource && !source) return null;
+	return {
+		id: typeof item.id === "string" ? item.id : typeof item.slug === "string" ? item.slug : url,
+		url,
+		content: cleanSearchResultText(content) ?? content,
+		description: cleanSearchResultText(typeof item.description === "string" ? item.description : typeof item.excerpt === "string" ? item.excerpt : void 0) ?? void 0,
+		type: isDocsSearchResultType(item.type) ? item.type : section ? "heading" : "page",
+		score: typeof item.score === "number" ? item.score : void 0,
+		section,
+		...source ? { source } : {}
+	};
+}
+function readMcpSearchToolPayload(payload) {
+	if (!payload || typeof payload !== "object" || !("result" in payload) || !payload.result || typeof payload.result !== "object") return null;
+	const result = payload.result;
+	if (result.structuredContent && typeof result.structuredContent === "object" && !Array.isArray(result.structuredContent)) return result.structuredContent;
+	const content = Array.isArray(result.content) ? result.content : [];
+	const resultText = content.length > 0 && content[0] && typeof content[0] === "object" && "text" in content[0] && typeof content[0].text === "string" ? content[0].text : null;
+	return resultText ? JSON.parse(resultText) : null;
+}
+async function createOllamaEmbedding(text, config, signal) {
+	const response = await fetch(`${(config.baseUrl ?? "http://127.0.0.1:11434").replace(/\/$/, "")}/api/embed`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({
+			model: config.model,
+			input: text
+		}),
+		signal
+	});
+	ensureOk(response, "Failed to create Ollama embedding");
+	const payload = await readResponseJson(response);
+	if (Array.isArray(payload.embeddings?.[0])) return payload.embeddings[0];
+	if (Array.isArray(payload.embedding)) return payload.embedding;
+	throw new Error("Ollama embedding response did not include an embedding vector.");
+}
+function getTypesenseSearchBase(config) {
+	return config.baseUrl.replace(/\/$/, "");
+}
+function quoteTypesenseFilterValue(value) {
+	return `\`${value.replace(/\\/gu, "\\\\").replace(/`/gu, "\\`")}\``;
+}
+const TYPESENSE_RETRIEVAL_SOURCE_FIELDS = [
+	{
+		name: "source_corpus_id",
+		type: "string",
+		optional: true
+	},
+	{
+		name: "source_document_id",
+		type: "string",
+		optional: true
+	},
+	{
+		name: "source_canonical_url",
+		type: "string",
+		optional: true
+	},
+	{
+		name: "source_scope_audience",
+		type: "string",
+		optional: true
+	},
+	{
+		name: "source_scope_locale",
+		type: "string[]",
+		optional: true
+	},
+	{
+		name: "source_scope_framework",
+		type: "string[]",
+		optional: true
+	},
+	{
+		name: "source_scope_version",
+		type: "string[]",
+		optional: true
+	},
+	{
+		name: "source_scope_version_groups",
+		type: "string",
+		optional: true
+	},
+	{
+		name: "source_scope_package",
+		type: "string[]",
+		optional: true
+	},
+	{
+		name: "source_scope_tags",
+		type: "string[]",
+		optional: true
+	},
+	{
+		name: "source_scope_truncated",
+		type: "string[]",
+		optional: true
+	},
+	{
+		name: "source_scope_conflicts",
+		type: "string[]",
+		optional: true
+	},
+	{
+		name: "source_last_modified",
+		type: "string",
+		optional: true
+	},
+	{
+		name: "source_digest",
+		type: "string",
+		optional: true
+	},
+	{
+		name: "source_index_generation",
+		type: "string",
+		optional: true
+	}
+];
+async function ensureTypesenseCollection(config, dimensions, signal, retryAfterCreateConflict = true, retryAfterAlterFailure = true) {
+	const baseUrl = getTypesenseSearchBase(config);
+	const headers = {
+		"X-TYPESENSE-API-KEY": config.adminApiKey ?? config.apiKey,
+		"Content-Type": "application/json"
+	};
+	const existing = await fetch(`${baseUrl}/collections/${encodeURIComponent(config.collection)}`, {
+		headers,
+		signal
+	});
+	if (existing.ok) {
+		const existingPayload = await readResponseJson(existing);
+		if (!Array.isArray(existingPayload?.fields)) throw new Error("Typesense collection response did not include a fields array.");
+		const existingFields = new Map(existingPayload.fields.flatMap((field) => typeof field.name === "string" ? [[field.name, field]] : []));
+		const incompatibleFields = TYPESENSE_RETRIEVAL_SOURCE_FIELDS.flatMap((expected) => {
+			const name = typeof expected.name === "string" ? expected.name : void 0;
+			const existingField = name ? existingFields.get(name) : void 0;
+			if (!name || !existingField) return [];
+			return existingField.type === expected.type && existingField.optional === true ? [] : [name];
+		});
+		if (incompatibleFields.length > 0) throw new Error(`Typesense collection has incompatible provenance fields: ${incompatibleFields.join(", ")}.`);
+		const missingFields = TYPESENSE_RETRIEVAL_SOURCE_FIELDS.filter((field) => typeof field.name === "string" && !existingFields.has(field.name));
+		const embeddingField = existingPayload.fields.find((field) => field.name === "embedding");
+		const expectedEmbeddingField = config.embeddings && dimensions ? {
+			name: "embedding",
+			type: "float[]",
+			num_dim: dimensions,
+			optional: true
+		} : void 0;
+		const replaceEmbedding = Boolean(expectedEmbeddingField && embeddingField && (embeddingField.type !== "float[]" || embeddingField.num_dim !== dimensions));
+		if (replaceEmbedding) ensureOk(await fetch(`${baseUrl}/collections/${encodeURIComponent(config.collection)}`, {
+			method: "PATCH",
+			headers,
+			body: JSON.stringify({ fields: [{
+				name: "embedding",
+				drop: true
+			}] }),
+			signal
+		}), "Failed to replace an incompatible Typesense embedding field");
+		const fieldsToAdd = [...missingFields, ...expectedEmbeddingField && (!embeddingField || replaceEmbedding) ? [expectedEmbeddingField] : []];
+		if (fieldsToAdd.length === 0) return;
+		const altered = await fetch(`${baseUrl}/collections/${encodeURIComponent(config.collection)}`, {
+			method: "PATCH",
+			headers,
+			body: JSON.stringify({ fields: fieldsToAdd }),
+			signal
+		});
+		if (!altered.ok && retryAfterAlterFailure) {
+			await ensureTypesenseCollection(config, dimensions, signal, retryAfterCreateConflict, false);
+			return;
+		}
+		ensureOk(altered, "Failed to update the Typesense search schema");
+		return;
+	}
+	if (existing.status !== 404) ensureOk(existing, "Failed to inspect Typesense collection");
+	const fields = [
+		{
+			name: "id",
+			type: "string"
+		},
+		{
+			name: "url",
+			type: "string"
+		},
+		{
+			name: "title",
+			type: "string"
+		},
+		{
+			name: "section",
+			type: "string",
+			optional: true
+		},
+		{
+			name: "content",
+			type: "string"
+		},
+		{
+			name: "description",
+			type: "string",
+			optional: true
+		},
+		{
+			name: "type",
+			type: "string"
+		},
+		{
+			name: "locale",
+			type: "string",
+			optional: true
+		},
+		{
+			name: "framework",
+			type: "string",
+			optional: true
+		},
+		{
+			name: "version",
+			type: "string",
+			optional: true
+		},
+		{
+			name: "package",
+			type: "string[]",
+			optional: true
+		},
+		{
+			name: "tags",
+			type: "string[]",
+			optional: true
+		},
+		...TYPESENSE_RETRIEVAL_SOURCE_FIELDS
+	];
+	if (config.embeddings && dimensions) fields.push({
+		name: "embedding",
+		type: "float[]",
+		num_dim: dimensions,
+		optional: true
+	});
+	const response = await fetch(`${baseUrl}/collections`, {
+		method: "POST",
+		headers,
+		body: JSON.stringify({
+			name: config.collection,
+			fields
+		}),
+		signal
+	});
+	if (response.status === 409 && retryAfterCreateConflict) {
+		await ensureTypesenseCollection(config, dimensions, signal, false, retryAfterAlterFailure);
+		return;
+	}
+	ensureOk(response, "Failed to create Typesense collection");
+}
+async function ensureTypesenseImportSucceeded(response, expectedRecords) {
+	ensureOk(response, "Failed to sync documents to Typesense");
+	const lines = (await response.text()).split(/\r?\n/u).filter((line) => line.trim());
+	if (lines.length !== expectedRecords) throw new Error(`Typesense acknowledged ${lines.length} of ${expectedRecords} imported records.`);
+	for (const [index, line] of lines.entries()) {
+		let result;
+		try {
+			result = JSON.parse(line);
+		} catch {
+			throw new Error(`Typesense import returned invalid JSON on record ${index + 1}.`);
+		}
+		if (result.success !== true) {
+			const detail = typeof result.error === "string" ? `: ${result.error}` : "";
+			throw new Error(`Typesense failed to import record ${index + 1}${detail}`);
+		}
+	}
+}
+function createTypesenseSearchAdapter(config) {
+	const adapter = {
+		name: "typesense",
+		async index(context) {
+			const adminApiKey = config.adminApiKey ?? config.apiKey;
+			const corpusId = resolveHostedHumanCorpusId(config.syncNamespace, context);
+			const documents = await enrichDocsSearchDocumentsWithSources({
+				documents: context.documents,
+				pages: context.pages,
+				audience: resolveDocsSearchAudience(context.audience),
+				chunking: context.chunking ?? { strategy: "section" },
+				locale: context.locale,
+				baseUrl: context.baseUrl,
+				indexGeneration: context.indexGeneration
+			});
+			const docsForImport = await Promise.all(documents.map(async (document) => {
+				const next = {
+					id: corpusId ? makeHostedProviderDocumentId(corpusId, document.id) : document.id,
+					url: document.url,
+					title: document.title,
+					section: document.section,
+					content: document.content,
+					description: document.description,
+					type: document.type,
+					locale: document.locale ?? document.source?.scope.locale?.[0],
+					framework: document.framework,
+					version: document.version,
+					package: document.package,
+					tags: document.tags,
+					...serializeHostedRetrievalSource(document.source, corpusId, document.id)
+				};
+				if (config.mode === "hybrid" && config.embeddings) next.embedding = await createOllamaEmbedding(`${document.title}\n${document.section ?? ""}\n${document.content}`.trim(), config.embeddings, context.signal);
+				return next;
+			}));
+			await ensureTypesenseCollection(config, Array.isArray(docsForImport[0]?.embedding) ? docsForImport[0].embedding.length : void 0, context.signal);
+			if (docsForImport.length > 0) await ensureTypesenseImportSucceeded(await fetch(`${getTypesenseSearchBase(config)}/collections/${encodeURIComponent(config.collection)}/documents/import?action=upsert`, {
+				method: "POST",
+				headers: {
+					"X-TYPESENSE-API-KEY": adminApiKey,
+					"Content-Type": "text/plain"
+				},
+				body: docsForImport.map((document) => JSON.stringify(document)).join("\n"),
+				signal: context.signal
+			}), docsForImport.length);
+		},
+		async search(query, context) {
+			return (await adapter.searchPage({
+				...query,
+				offset: 0,
+				[DOCS_UNPAGINATED_PROVIDER_QUERY]: true
+			}, context)).results;
+		},
+		async searchPage(query, context) {
+			const exactPagination = !query[DOCS_UNPAGINATED_PROVIDER_QUERY];
+			const corpusId = resolveHostedHumanCorpusId(config.syncNamespace, context);
+			const scopedDocumentIds = resolveProviderScopeDocumentIds(query, context, corpusId);
+			if (scopedDocumentIds === DOCS_PROVIDER_SCOPE_FILTER_OVERFLOW) throw new Error("Typesense scope filters exceed the provider pagination limit.");
+			if (scopedDocumentIds?.length === 0) return {
+				results: [],
+				total: 0
+			};
+			const pageSize = query.limit ?? config.maxResults ?? DEFAULT_SEARCH_LIMIT;
+			if ((query.offset ?? 0) % pageSize !== 0) throw new Error("Typesense search offset does not match its page boundary.");
+			const params = new URLSearchParams({
+				q: query.query,
+				query_by: (config.queryBy ?? [
+					"title",
+					"section",
+					"content",
+					"description"
+				]).join(","),
+				per_page: String(pageSize),
+				prioritize_exact_match: "true",
+				num_typos: "2",
+				highlight_fields: "content,title,section,description",
+				page: String(Math.floor((query.offset ?? 0) / pageSize) + 1)
+			});
+			if (config.mode === "hybrid" && config.embeddings) {
+				const vector = await createOllamaEmbedding(query.query, config.embeddings, context.signal);
+				params.set("vector_query", `embedding:([${vector.join(",")}],k:${Math.max((query.limit ?? 10) * 4, 20)})`);
+			}
+			const filterClauses = [
+				corpusId ? `source_corpus_id:=${quoteTypesenseFilterValue(corpusId)}` : void 0,
+				context.indexGeneration ? `source_index_generation:=${quoteTypesenseFilterValue(context.indexGeneration)}` : void 0,
+				scopedDocumentIds ? `id:=[${scopedDocumentIds.map(quoteTypesenseFilterValue).join(",")}]` : void 0
+			].filter((value) => Boolean(value));
+			const filterBy = filterClauses.length > 0 ? filterClauses.join(" && ") : void 0;
+			if (filterBy && filterBy.length > MAX_PROVIDER_SCOPE_FILTER_CHARS) throw new Error("Typesense scope filters exceed the provider pagination limit.");
+			const response = filterBy ? await fetch(`${getTypesenseSearchBase(config)}/multi_search`, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					"X-TYPESENSE-API-KEY": config.apiKey
+				},
+				body: JSON.stringify({ searches: [{
+					collection: config.collection,
+					...Object.fromEntries(params),
+					filter_by: filterBy
+				}] }),
+				signal: context.signal
+			}) : await fetch(`${getTypesenseSearchBase(config)}/collections/${encodeURIComponent(config.collection)}/documents/search?${params.toString()}`, {
+				headers: { "X-TYPESENSE-API-KEY": config.apiKey },
+				signal: context.signal
+			});
+			ensureOk(response, "Typesense search failed");
+			const rawPayload = await readResponseJson(response);
+			const payload = filterBy ? rawPayload.results?.[0] ?? {} : rawPayload;
+			if (exactPagination && payload.search_cutoff !== void 0 && payload.search_cutoff !== false) throw new Error("Typesense search was cut off before exact pagination completed.");
+			const results = (payload.hits ?? []).flatMap((hit) => {
+				const document = hit.document ?? {};
+				if (!hostedRecordMatchesCorpus(document, corpusId)) return [];
+				const section = typeof document.section === "string" ? document.section : void 0;
+				const content = typeof document.title === "string" ? section ? `${document.title} — ${section}` : document.title : typeof document.content === "string" ? document.content : "Untitled result";
+				const description = hit.highlights?.find((item) => item.field === "content")?.snippet ?? hit.highlights?.find((item) => item.field === "description")?.snippet ?? (typeof document.description === "string" ? document.description : void 0);
+				const source = readHostedRetrievalSource(document);
+				if (hasHostedRetrievalSource(document) && !source) return [];
+				return [{
+					id: readHostedSourceDocumentId(document) ?? (typeof document.id === "string" ? document.id : String(document.url ?? content)),
+					url: typeof document.url === "string" ? document.url : "/docs",
+					content: cleanSearchResultText(content) ?? content,
+					description: cleanSearchResultText(description),
+					type: typeof document.type === "string" && [
+						"page",
+						"heading",
+						"text"
+					].includes(document.type) ? document.type : section ? "heading" : "page",
+					score: hit.text_match,
+					section,
+					...source ? { source } : {}
+				}];
+			});
+			const exactTotal = typeof payload.found === "number" && Number.isSafeInteger(payload.found) && payload.found >= 0 ? payload.found : void 0;
+			if (exactPagination && exactTotal === void 0) throw new Error("Typesense search did not return an exact result total.");
+			const total = exactTotal ?? results.length;
+			if (exactPagination && total > MAX_HOSTED_PROVIDER_CURSOR_RESULTS) throw new Error("Typesense search exceeds the exact cursor pagination window.");
+			if (exactPagination && (query.offset ?? 0) + results.length < total && results.length !== pageSize) throw new Error("Typesense search returned an incomplete non-final page.");
+			return {
+				results,
+				total
+			};
+		}
+	};
+	return adapter;
+}
+function resolveSearchRequestConfig(search, requestUrl, options) {
+	if (!search || search === true || typeof search !== "object" || search.provider !== "mcp") return search;
+	if (options) {
+		const localSearch = resolveLocalDocsMcpSearchConfig(search, options.localMcp, requestUrl);
+		if (localSearch !== search) return localSearch;
+	}
+	if (!requestUrl) return search;
+	const resolvedEndpoint = new URL(search.endpoint, requestUrl);
+	const usesDefaultSearchTool = (search.toolName ?? "search_docs") === "search_docs";
+	const isSameOrigin = resolvedEndpoint.origin === new URL(requestUrl).origin;
+	return {
+		...search,
+		endpoint: resolvedEndpoint.toString(),
+		forwardAudience: search.forwardAudience ?? (usesDefaultSearchTool && isSameOrigin)
+	};
+}
+function isLocalDocsMcpSearchEndpoint(search, localMcp, requestUrl) {
+	if (localMcp === false || localMcp !== null && typeof localMcp === "object" && (localMcp.enabled === false || localMcp.tools?.searchDocs === false) || (search.toolName ?? "search_docs") !== "search_docs") return false;
+	const endpoint = search.endpoint.trim();
+	if (!endpoint) return false;
+	const route = localMcp !== null && typeof localMcp === "object" ? localMcp.route : void 0;
+	let endpointPath;
+	try {
+		if (endpoint.startsWith("/") && !endpoint.startsWith("//")) endpointPath = new URL(endpoint, "https://local.docs.invalid").pathname;
+		else {
+			if (!requestUrl) return false;
+			const request = new URL(requestUrl);
+			const resolvedEndpoint = new URL(endpoint, request);
+			if (resolvedEndpoint.origin !== request.origin || resolvedEndpoint.username || resolvedEndpoint.password) return false;
+			endpointPath = resolvedEndpoint.pathname;
+		}
+	} catch {
+		return false;
+	}
+	return isDocsMcpResourcePath(endpointPath, route);
+}
+function resolveLocalDocsMcpSearchConfig(search, localMcp, requestUrl) {
+	if (!search || search === true || typeof search !== "object" || search.provider !== "mcp" || !isLocalDocsMcpSearchEndpoint(search, localMcp, requestUrl)) return search;
+	return {
+		provider: "simple",
+		enabled: search.enabled,
+		maxResults: search.maxResults,
+		chunking: search.chunking
+	};
+}
+/**
+* Resolve the public search audience without allowing malformed values to opt into agent content.
+* Human search remains the default for omitted, legacy, and unknown query values.
+*/
+function resolveDocsSearchAudience(value) {
+	return value === "agent" ? "agent" : "human";
+}
+function resolveAskAISearchRequestConfig(options) {
+	if (!options.useMcp) return resolveSearchRequestConfig(options.search, options.requestUrl);
+	if (typeof options.useMcp === "object") return resolveSearchRequestConfig({
+		...options.useMcp,
+		provider: "mcp"
+	}, options.requestUrl);
+	if (options.mcpEnabled === false || options.mcpSearchEnabled === false || !options.mcpEndpoint) return resolveSearchRequestConfig(options.search, options.requestUrl);
+	return resolveSearchRequestConfig({
+		provider: "mcp",
+		endpoint: options.mcpEndpoint
+	}, options.requestUrl);
+}
+function createMcpSearchAdapter(config) {
+	async function runMcpSearch(query, context, paginated) {
+		const endpoint = resolveMcpEndpoint(config.endpoint);
+		const protocolVersion = config.protocolVersion ?? DEFAULT_MCP_PROTOCOL_VERSION;
+		const toolName = config.toolName ?? "search_docs";
+		const forwardAudience = config.forwardAudience === true;
+		const audience = resolveDocsSearchAudience(query.audience);
+		const baseHeaders = config.headers ?? {};
+		if (audience === "human" && !forwardAudience) throw new Error("MCP human-projection search requires forwardAudience: true on an audience-aware tool.");
+		const initializeResponse = await fetch(endpoint, {
+			method: "POST",
+			headers: {
+				...baseHeaders,
+				"Content-Type": "application/json",
+				accept: "application/json, text/event-stream",
+				"mcp-protocol-version": protocolVersion
+			},
+			body: JSON.stringify({
+				jsonrpc: "2.0",
+				id: 1,
+				method: "initialize",
+				params: {
+					protocolVersion,
+					capabilities: {},
+					clientInfo: {
+						name: "@farming-labs/docs-search",
+						version: "0.1.2"
+					}
+				}
+			}),
+			signal: context.signal
+		});
+		ensureOk(initializeResponse, "MCP search initialization failed");
+		ensureJsonRpcOk(await readMcpResponsePayload(initializeResponse), "MCP search initialization failed");
+		const sessionId = initializeResponse.headers.get("mcp-session-id") ?? void 0;
+		try {
+			ensureOk(await fetch(endpoint, {
+				method: "POST",
+				headers: {
+					...baseHeaders,
+					"Content-Type": "application/json",
+					accept: "application/json, text/event-stream",
+					"mcp-protocol-version": protocolVersion,
+					...sessionId ? { "mcp-session-id": sessionId } : {}
+				},
+				body: JSON.stringify({
+					jsonrpc: "2.0",
+					method: "notifications/initialized",
+					params: {}
+				}),
+				signal: context.signal
+			}), "MCP initialized notification failed");
+			const pageSize = query.limit ?? config.maxResults ?? DEFAULT_SEARCH_LIMIT;
+			const callRemoteSearchPage = async (providerCursor, id) => {
+				const searchResponse = await fetch(endpoint, {
+					method: "POST",
+					headers: {
+						...baseHeaders,
+						"Content-Type": "application/json",
+						accept: "application/json, text/event-stream",
+						"mcp-protocol-version": protocolVersion,
+						...sessionId ? { "mcp-session-id": sessionId } : {}
+					},
+					body: JSON.stringify({
+						jsonrpc: "2.0",
+						id,
+						method: "tools/call",
+						params: {
+							name: toolName,
+							arguments: {
+								query: query.query,
+								limit: pageSize,
+								locale: query.locale,
+								...query.explain ? { explain: true } : {},
+								...providerCursor !== void 0 ? { cursor: providerCursor } : {},
+								...forwardAudience ? { audience } : {},
+								...query.filters?.framework ? { framework: query.filters.framework } : {},
+								...query.filters?.version ? { version: query.filters.version } : {},
+								...query.filters?.package ? { package: query.filters.package } : {},
+								...query.filters?.tags ? { tags: query.filters.tags } : {}
+							}
+						}
+					}),
+					signal: context.signal
+				});
+				ensureOk(searchResponse, "MCP search request failed");
+				const payload = await readMcpResponsePayload(searchResponse);
+				ensureJsonRpcOk(payload, "MCP search request failed");
+				const parsed = readMcpSearchToolPayload(payload);
+				if (!parsed) return {
+					parsed,
+					rawResults: [],
+					results: []
+				};
+				if (hasDocsSearchFilters(query.filters ?? {})) {
+					if (Array.isArray(parsed) || parsed.format !== "docs-search.v1") {
+						if (paginated) throw new Error("MCP search returned unverifiable pagination data.");
+						return {
+							parsed,
+							rawResults: [],
+							results: []
+						};
+					}
+					const echoedFilters = parseVerifiedMcpSearchFilters(parsed.filters);
+					if (!echoedFilters || !docsSearchFiltersMatch(query.filters ?? {}, echoedFilters)) {
+						if (paginated) throw new Error("MCP search returned mismatched scope filters.");
+						return {
+							parsed,
+							rawResults: [],
+							results: []
+						};
+					}
+				}
+				const rawResults = Array.isArray(parsed) ? parsed : Array.isArray(parsed.results) ? parsed.results : Array.isArray(parsed.pages) ? parsed.pages : [];
+				return {
+					parsed,
+					rawResults,
+					results: rawResults.map((result) => mapMcpSearchResult(result, endpoint)).filter((result) => Boolean(result))
+				};
+			};
+			if (!paginated) return (await callRemoteSearchPage(void 0, 2)).results;
+			const targetOffset = query.offset ?? 0;
+			if (targetOffset === 0 && query.cursor !== void 0 || targetOffset > 0 && query.cursor === void 0) throw new Error("MCP search continuation is missing or misplaced its provider cursor.");
+			let consumed = 0;
+			let remoteCursor;
+			let expectedTotal;
+			const replayResultDigests = [];
+			for (let pageIndex = 0; pageIndex < MAX_MCP_SEARCH_CURSOR_REPLAY_PAGES; pageIndex += 1) {
+				const { parsed, rawResults, results } = await callRemoteSearchPage(remoteCursor, pageIndex + 2);
+				if (!parsed) {
+					if (targetOffset === 0) return {
+						results: [],
+						total: 0
+					};
+					throw new Error("MCP search continuation ended before the requested page.");
+				}
+				if (Array.isArray(parsed) || parsed.format !== "docs-search.v1" || results.length !== rawResults.length || parsed.resultCount !== void 0 && parsed.resultCount !== results.length || typeof parsed.total !== "number" || !Number.isSafeInteger(parsed.total) || parsed.total < consumed + results.length || typeof parsed.hasMore !== "boolean" || parsed.nextCursor !== void 0 && (typeof parsed.nextCursor !== "string" || parsed.nextCursor.length > 768)) throw new Error("MCP search returned malformed paginated results.");
+				const total = parsed.total;
+				const nextCursor = typeof parsed.nextCursor === "string" ? parsed.nextCursor : void 0;
+				const hasMore = consumed + results.length < total;
+				if (expectedTotal !== void 0 && total !== expectedTotal || parsed.hasMore !== hasMore || nextCursor !== void 0 !== hasMore || hasMore && results.length === 0) throw new Error("MCP search returned inconsistent pagination metadata.");
+				expectedTotal ??= total;
+				if (total > MAX_MCP_SEARCH_CURSOR_RESULTS) throw new Error("MCP search exceeds its bounded exact pagination window.");
+				replayResultDigests.push(...results.map((result) => hashDocsRetrievalValue(JSON.stringify(result))));
+				const nextOffset = consumed + results.length;
+				const nextCheckpoint = hasMore ? hashDocsRetrievalValue(JSON.stringify({
+					format: "docs-mcp-search-replay.v1",
+					total,
+					nextOffset,
+					resultDigests: replayResultDigests
+				})) : void 0;
+				if (nextOffset === targetOffset && nextCheckpoint !== query.cursor) throw new Error("MCP search continuation cursor is stale.");
+				if (consumed === targetOffset) return {
+					results,
+					total,
+					...nextCheckpoint !== void 0 ? { nextCursor: nextCheckpoint } : {}
+				};
+				if (!hasMore || nextCursor === void 0) throw new Error("MCP search continuation ended before the requested page.");
+				consumed = nextOffset;
+				if (consumed > targetOffset) throw new Error("MCP search continuation offset does not match a page boundary.");
+				remoteCursor = nextCursor;
+			}
+			throw new Error("MCP search exceeds its bounded cursor replay limit.");
+		} finally {
+			if (sessionId) {
+				const cleanupController = new AbortController();
+				const cleanupTimeout = setTimeout(() => cleanupController.abort(), MCP_SESSION_CLEANUP_TIMEOUT_MS);
+				try {
+					await fetch(endpoint, {
+						method: "DELETE",
+						headers: {
+							...baseHeaders,
+							"mcp-protocol-version": protocolVersion,
+							"mcp-session-id": sessionId
+						},
+						signal: cleanupController.signal
+					});
+				} catch {} finally {
+					clearTimeout(cleanupTimeout);
+				}
+			}
+		}
+	}
+	return {
+		name: "mcp",
+		async search(query, context) {
+			return await runMcpSearch(query, context, false);
+		},
+		async searchPage(query, context) {
+			return await runMcpSearch(query, context, true);
+		}
+	};
+}
+function getAlgoliaSearchBase(config) {
+	return `https://${config.appId}-dsn.algolia.net`;
+}
+function getAlgoliaAdminBase(config) {
+	return `https://${config.appId}.algolia.net`;
+}
+function getAlgoliaAdminHeaders(config) {
+	return {
+		"Content-Type": "application/json",
+		"X-Algolia-Application-Id": config.appId,
+		"X-Algolia-API-Key": config.adminApiKey ?? config.searchApiKey
+	};
+}
+async function waitForAlgoliaTask(config, taskId, signal) {
+	const deadline = Date.now() + 6e4;
+	for (let attempt = 0; Date.now() < deadline; attempt += 1) {
+		const response = await fetch(`${getAlgoliaAdminBase(config)}/1/indexes/${encodeURIComponent(config.indexName)}/task/${encodeURIComponent(String(taskId))}`, {
+			headers: getAlgoliaAdminHeaders(config),
+			signal
+		});
+		ensureOk(response, "Failed to inspect Algolia sync task");
+		const payload = await readResponseJson(response);
+		if (payload?.status === "published") return;
+		if (payload?.status !== "notPublished") throw new Error("Algolia sync task returned an unknown status.");
+		const delay = Math.min(100 * 2 ** Math.min(attempt, 4), 2e3);
+		await new Promise((resolve, reject) => {
+			let timer;
+			const onAbort = () => {
+				clearTimeout(timer);
+				reject(signal?.reason ?? /* @__PURE__ */ new Error("Algolia sync was aborted."));
+			};
+			timer = setTimeout(() => {
+				signal?.removeEventListener("abort", onAbort);
+				resolve();
+			}, Math.min(delay, Math.max(1, deadline - Date.now())));
+			if (signal?.aborted) onAbort();
+			else signal?.addEventListener("abort", onAbort, { once: true });
+		});
+	}
+	throw new Error("Timed out waiting for Algolia to publish the synced index.");
+}
+async function executeAlgoliaBatch(config, requests, message, signal) {
+	for (let offset = 0; offset < requests.length; offset += ALGOLIA_BATCH_OPERATIONS) {
+		const batch = requests.slice(offset, offset + ALGOLIA_BATCH_OPERATIONS);
+		const response = await fetch(`${getAlgoliaAdminBase(config)}/1/indexes/${encodeURIComponent(config.indexName)}/batch`, {
+			method: "POST",
+			headers: getAlgoliaAdminHeaders(config),
+			body: JSON.stringify({ requests: batch }),
+			signal
+		});
+		ensureOk(response, message);
+		const payload = await readResponseJson(response);
+		if (typeof payload?.taskID !== "string" && typeof payload?.taskID !== "number") throw new Error("Algolia sync response did not include a task ID.");
+		await waitForAlgoliaTask(config, payload.taskID, signal);
+	}
+}
+function quoteAlgoliaFilterValue(value) {
+	return `"${value.replace(/\\/gu, "\\\\").replace(/"/gu, "\\\"")}"`;
+}
+function createAlgoliaSearchAdapter(config) {
+	const adapter = {
+		name: "algolia",
+		async index(context) {
+			if (!config.adminApiKey) return;
+			const corpusId = resolveHostedHumanCorpusId(config.syncNamespace, context);
+			await executeAlgoliaBatch(config, (await enrichDocsSearchDocumentsWithSources({
+				documents: context.documents,
+				pages: context.pages,
+				audience: resolveDocsSearchAudience(context.audience),
+				chunking: context.chunking ?? { strategy: "section" },
+				locale: context.locale,
+				baseUrl: context.baseUrl,
+				indexGeneration: context.indexGeneration
+			})).map((document) => ({
+				action: "addObject",
+				body: buildAlgoliaRecord(document, corpusId)
+			})), "Failed to sync documents to Algolia", context.signal);
+		},
+		async search(query, context) {
+			return (await adapter.searchPage({
+				...query,
+				offset: 0,
+				[DOCS_UNPAGINATED_PROVIDER_QUERY]: true
+			}, context)).results;
+		},
+		async searchPage(query, context) {
+			const exactPagination = !query[DOCS_UNPAGINATED_PROVIDER_QUERY];
+			const corpusId = resolveHostedHumanCorpusId(config.syncNamespace, context);
+			const scopedDocumentIds = resolveProviderScopeDocumentIds(query, context, corpusId);
+			if (scopedDocumentIds === DOCS_PROVIDER_SCOPE_FILTER_OVERFLOW) throw new Error("Algolia scope filters exceed the provider pagination limit.");
+			if (scopedDocumentIds?.length === 0) return {
+				results: [],
+				total: 0
+			};
+			const scopedIdsFilter = scopedDocumentIds?.map((id) => `objectID:${quoteAlgoliaFilterValue(id)}`).join(" OR ");
+			const filterClauses = [
+				corpusId ? `_tags:${quoteAlgoliaFilterValue(corpusId)}` : void 0,
+				context.indexGeneration ? `_tags:${quoteAlgoliaFilterValue(getHostedIndexGenerationTag(context.indexGeneration))}` : void 0,
+				scopedIdsFilter ? corpusId || context.indexGeneration ? `(${scopedIdsFilter})` : scopedIdsFilter : void 0
+			].filter((value) => Boolean(value));
+			const filters = filterClauses.length > 0 ? filterClauses.join(" AND ") : void 0;
+			if (filters && filters.length > MAX_PROVIDER_SCOPE_FILTER_CHARS) throw new Error("Algolia scope filters exceed the provider pagination limit.");
+			const pageSize = query.limit ?? config.maxResults ?? DEFAULT_SEARCH_LIMIT;
+			if ((query.offset ?? 0) % pageSize !== 0) throw new Error("Algolia search offset does not match its page boundary.");
+			const response = await fetch(`${getAlgoliaSearchBase(config)}/1/indexes/${encodeURIComponent(config.indexName)}/query`, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					"X-Algolia-Application-Id": config.appId,
+					"X-Algolia-API-Key": config.searchApiKey
+				},
+				body: JSON.stringify({
+					query: query.query,
+					hitsPerPage: pageSize,
+					page: Math.floor((query.offset ?? 0) / pageSize),
+					restrictSearchableAttributes: [
+						"title",
+						"section",
+						"content",
+						"description"
+					],
+					attributesToSnippet: ["content:20"],
+					...filters ? { filters } : {}
+				}),
+				signal: context.signal
+			});
+			ensureOk(response, "Algolia search failed");
+			const payload = await readResponseJson(response);
+			const results = (payload.hits ?? []).flatMap((hit) => {
+				if (!hostedRecordMatchesCorpus(hit, corpusId)) return [];
+				const title = typeof hit.title === "string" ? hit.title : "Untitled result";
+				const section = typeof hit.section === "string" ? hit.section : void 0;
+				const source = readHostedRetrievalSource(hit);
+				if (hasHostedRetrievalSource(hit) && !source) return [];
+				return [{
+					id: readHostedSourceDocumentId(hit) ?? hit.objectID ?? String(hit.url ?? title),
+					url: typeof hit.url === "string" ? hit.url : "/docs",
+					content: cleanSearchResultText(section ? `${title} — ${section}` : title) ?? title,
+					description: cleanSearchResultText(hit._snippetResult?.content?.value ?? hit._snippetResult?.description?.value ?? (typeof hit.description === "string" ? hit.description : void 0)),
+					type: typeof hit.type === "string" && [
+						"page",
+						"heading",
+						"text"
+					].includes(hit.type) ? hit.type : section ? "heading" : "page",
+					score: hit._rankingInfo?.nbTypos != null ? 100 - hit._rankingInfo.nbTypos : void 0,
+					section,
+					...source ? { source } : {}
+				}];
+			});
+			const exactTotal = typeof payload.nbHits === "number" && Number.isSafeInteger(payload.nbHits) && payload.nbHits >= 0 ? payload.nbHits : void 0;
+			const exactPageCount = typeof payload.nbPages === "number" && Number.isSafeInteger(payload.nbPages) && payload.nbPages >= 0 ? payload.nbPages : void 0;
+			if (exactPagination && (exactTotal === void 0 || exactPageCount === void 0)) throw new Error("Algolia search did not return exact reachable pagination metadata.");
+			const total = exactTotal ?? results.length;
+			if (exactPagination && total > MAX_HOSTED_PROVIDER_CURSOR_RESULTS) throw new Error("Algolia search exceeds the exact cursor pagination window.");
+			if (exactPagination && payload.exhaustiveNbHits === false) throw new Error("Algolia search returned an approximate result total.");
+			if (exactPagination && exactPageCount !== void 0 && total > exactPageCount * pageSize) throw new Error("Algolia search total exceeds its reachable pagination window.");
+			if (exactPagination && (query.offset ?? 0) + results.length < total && results.length !== pageSize) throw new Error("Algolia search returned an incomplete non-final page.");
+			return {
+				results,
+				total
+			};
+		}
+	};
+	return adapter;
+}
+async function resolveSearchAdapter(search, context) {
+	const raw = search.raw;
+	if (search.provider === "custom" && raw?.provider === "custom") return typeof raw.adapter === "function" ? await raw.adapter(context) : raw.adapter;
+	if (search.provider === "typesense" && raw?.provider === "typesense") return createTypesenseSearchAdapter(raw);
+	if (search.provider === "mcp" && raw?.provider === "mcp") return createMcpSearchAdapter(raw);
+	if (search.provider === "algolia" && raw?.provider === "algolia") return createAlgoliaSearchAdapter(raw);
+	return createSimpleSearchAdapter();
+}
+function shouldSyncOnSearch(search) {
+	const raw = search.raw;
+	if (search.provider === "algolia" && raw?.provider === "algolia") return (raw.syncOnSearch ?? Boolean(raw.adminApiKey)) && Boolean(raw.adminApiKey);
+	if (search.provider === "typesense" && raw?.provider === "typesense") return (raw.syncOnSearch ?? Boolean(raw.adminApiKey)) && Boolean(raw.adminApiKey);
+	return false;
+}
+function getSyncKey(search, context) {
+	const raw = search.raw;
+	if (search.provider === "algolia" && raw?.provider === "algolia") {
+		const corpusId = resolveHostedHumanCorpusId(raw.syncNamespace, context) ?? "__unowned__";
+		return `algolia:${raw.appId}:${raw.indexName}:${corpusId}:${context.locale ?? "__default__"}`;
+	}
+	if (search.provider === "typesense" && raw?.provider === "typesense") {
+		const corpusId = resolveHostedHumanCorpusId(raw.syncNamespace, context) ?? "__unowned__";
+		return `typesense:${raw.baseUrl}:${raw.collection}:${corpusId}:${context.locale ?? "__default__"}`;
+	}
+	if (search.provider === "mcp" && raw?.provider === "mcp") return `mcp:${raw.endpoint}:${context.locale ?? "__default__"}`;
+	return `${search.provider}:${context.locale ?? "__default__"}`;
+}
+function getSearchSyncFingerprint(search, context, indexGeneration) {
+	const raw = search.raw;
+	const providerConfig = search.provider === "typesense" && raw?.provider === "typesense" ? {
+		syncNamespace: raw.syncNamespace?.trim() || void 0,
+		mode: raw.mode ?? "keyword",
+		embeddings: raw.embeddings ? {
+			provider: raw.embeddings.provider,
+			model: raw.embeddings.model,
+			baseUrl: raw.embeddings.baseUrl
+		} : void 0
+	} : search.provider === "algolia" && raw?.provider === "algolia" ? { syncNamespace: raw.syncNamespace?.trim() || void 0 } : void 0;
+	return hashDocsRetrievalValue(JSON.stringify({
+		format: "docs-search-sync.v1",
+		indexGeneration,
+		canonicalBaseUrl: context.baseUrl,
+		provider: search.provider,
+		providerConfig
+	}));
+}
+async function maybeSyncSearchIndex(adapter, search, context) {
+	if (!shouldSyncOnSearch(search) || typeof adapter.index !== "function") return;
+	const syncKey = getSyncKey(search, context);
+	const indexGeneration = context.indexGeneration ?? await buildDocsSearchIndexGeneration(context.pages, {
+		audience: resolveDocsSearchAudience(context.audience),
+		chunking: context.chunking ?? search.chunking,
+		locale: context.locale,
+		baseUrl: context.baseUrl
+	});
+	context.indexGeneration = indexGeneration;
+	const syncFingerprint = getSearchSyncFingerprint(search, context, indexGeneration);
+	while (true) {
+		const inFlight = syncingIndexes.get(syncKey);
+		if (inFlight) {
+			try {
+				await inFlight.promise;
+			} catch (error) {
+				if (inFlight.fingerprint === syncFingerprint) throw error;
+			}
+			continue;
+		}
+		if (syncedIndexes.get(syncKey) === syncFingerprint) return;
+		const sync = adapter.index(context).then(() => {
+			syncedIndexes.set(syncKey, syncFingerprint);
+		});
+		syncingIndexes.set(syncKey, {
+			fingerprint: syncFingerprint,
+			promise: sync
+		});
+		try {
+			await sync;
+		} finally {
+			if (syncingIndexes.get(syncKey)?.promise === sync) syncingIndexes.delete(syncKey);
+		}
+	}
+}
+function normalizeDocsSearchAdapterPage(value) {
+	if (Array.isArray(value)) return {
+		results: value,
+		total: value.length
+	};
+	if (!value || !Array.isArray(value.results) || !Number.isSafeInteger(value.total) || value.total < 0 || value.results.length > value.total || value.nextCursor !== void 0 && (typeof value.nextCursor !== "string" || value.nextCursor.length === 0 || JSON.stringify([
+		1,
+		"provider",
+		value.total,
+		value.nextCursor
+	]).length > MAX_SEARCH_PROVIDER_CURSOR_STATE_CHARS)) throw new Error("Search adapter returned invalid pagination metadata.");
+	return value;
+}
+async function performDocsSearchInternal(options) {
+	const search = normalizeDocsSearchConfig(options.search);
+	if (!search.enabled) {
+		if (options.paginationMode === "provider" || options.expectedTotal !== void 0 && options.expectedTotal !== 0) throw new DocsPaginationCursorError();
+		return {
+			results: [],
+			total: 0,
+			paginationMode: "local"
+		};
+	}
+	const audience = resolveDocsSearchAudience(options.audience);
+	const filters = normalizeDocsSearchFilters(options.filters);
+	const hasFilters = hasDocsSearchFilters(filters);
+	const accessiblePages = filterDocsPagesByAccess(options.pages, options.principal);
+	const accessibleGenerationPages = filterDocsPagesByAccess(options.generationPages ?? options.pages, options.principal);
+	const corpusPages = accessiblePages.map((page) => localizeDocsSearchPage(page, options.locale));
+	const indexBaseUrl = options.syncBaseUrl === null ? void 0 : options.syncBaseUrl ?? options.baseUrl;
+	const scopedPages = hasFilters ? corpusPages.filter((page) => docsSearchPageMatchesFilters(resolveDocsSearchPageScope(page), filters)) : corpusPages;
+	let resolvedDocuments;
+	const getDocuments = () => {
+		if (!resolvedDocuments) resolvedDocuments = buildDocsSearchDocuments(scopedPages, search.chunking, audience);
+		return resolvedDocuments;
+	};
+	const context = {
+		pages: scopedPages,
+		get documents() {
+			return getDocuments();
+		},
+		set documents(documents) {
+			resolvedDocuments = documents;
+		},
+		audience,
+		locale: options.locale,
+		pathname: options.pathname,
+		siteTitle: options.siteTitle,
+		baseUrl: options.baseUrl,
+		indexBaseUrl,
+		chunking: search.chunking,
+		deferSourceProvenance: true,
+		signal: options.signal
+	};
+	const query = {
+		query: options.query,
+		limit: options.limit ?? search.maxResults,
+		...options.paginated ? { offset: options.offset ?? 0 } : {},
+		...options.providerCursor !== void 0 ? { cursor: options.providerCursor } : {},
+		locale: options.locale,
+		pathname: options.pathname,
+		audience,
+		...hasFilters ? { filters } : {},
+		...options.explain ? { explain: true } : {}
+	};
+	let currentIndexGeneration;
+	const getCurrentIndexGeneration = () => {
+		currentIndexGeneration ??= options.indexGeneration ? Promise.resolve(options.indexGeneration) : buildDocsSearchIndexGeneration(accessibleGenerationPages, {
+			audience,
+			chunking: search.chunking,
+			locale: options.locale,
+			baseUrl: options.baseUrl
+		});
+		return currentIndexGeneration;
+	};
+	const requireCurrentIndexGeneration = search.provider === "algolia" || search.provider === "typesense";
+	let hostedIndexGeneration;
+	const getHostedIndexGeneration = () => {
+		hostedIndexGeneration ??= audience === "human" ? getCurrentIndexGeneration() : buildDocsSearchIndexGeneration(accessibleGenerationPages, {
+			audience: "human",
+			chunking: search.chunking,
+			locale: options.locale,
+			baseUrl: indexBaseUrl
+		});
+		return hostedIndexGeneration;
+	};
+	let explanationWarnings;
+	const getExplanationWarnings = () => {
+		explanationWarnings ??= buildDocsSearchWarnings({
+			pages: corpusPages,
+			results: [],
+			filters,
+			query: options.query,
+			audience,
+			baseUrl: options.baseUrl,
+			completeResultSet: true
+		});
+		return explanationWarnings;
+	};
+	let explanationUnverifiableAmbiguityFields;
+	const getExplanationUnverifiableAmbiguityFields = () => {
+		explanationUnverifiableAmbiguityFields ??= new Set(SEARCH_AMBIGUITY_FIELDS.filter((field) => corpusPages.some((page) => {
+			if (scoreDocument(options.query, pageToSearchDocument(page, audience)) <= 0) return false;
+			const scope = resolveDocsSearchPageScope(page);
+			if (hasFilters && !docsSearchPageMatchesFilters(scope, filters)) return false;
+			return scope.conflicts.includes(field) || scope.declarations[field].length === 0;
+		})));
+		return explanationUnverifiableAmbiguityFields;
+	};
+	const finalizeResults = async (results, ranking = "lexical") => {
+		const enriched = await enrichDocsSearchResultsWithSources({
+			results,
+			pages: scopedPages,
+			generationPages: options.generationPages ?? options.pages,
+			audience,
+			chunking: search.chunking,
+			locale: options.locale,
+			baseUrl: options.baseUrl,
+			indexGeneration: options.indexGeneration,
+			strictExternalOrigins: options.strictExternalOrigins,
+			filters,
+			requireCurrentIndexGeneration
+		});
+		if (!options.explain) return enriched.map((result) => {
+			const { explanation: _explanation, ...resultWithoutExplanation } = result;
+			return resultWithoutExplanation;
+		});
+		return explainDocsSearchResults({
+			results: enriched,
+			documents: getDocuments(),
+			query: options.query,
+			filters,
+			warnings: getExplanationWarnings(),
+			unverifiableAmbiguityFields: getExplanationUnverifiableAmbiguityFields(),
+			provider: search.provider,
+			rankOffset: options.offset ?? 0,
+			resolveRankingStrategy: typeof ranking === "function" ? ranking : () => ranking
+		});
+	};
+	const createLocalPage = async () => {
+		const fallback = options.paginated ? await createSimpleSearchAdapter().searchPage(query, context) : normalizeDocsSearchAdapterPage(await createSimpleSearchAdapter().search(query, context));
+		if (options.expectedTotal !== void 0 && fallback.total !== options.expectedTotal) throw new DocsPaginationCursorError();
+		return {
+			results: await finalizeResults(fallback.results, "lexical"),
+			total: options.paginated ? fallback.total : fallback.results.length,
+			paginationMode: "local"
+		};
+	};
+	const fallBackFromProvider = () => {
+		if (options.paginationMode === "provider") throw new DocsPaginationCursorError();
+		return createLocalPage();
+	};
+	if (options.paginated && options.paginationMode === "local") return createLocalPage();
+	try {
+		const adapter = await resolveSearchAdapter(search, context);
+		if (shouldSyncOnSearch(search) && typeof adapter.index === "function") {
+			const syncPages = audience === "agent" || hasFilters ? corpusPages : scopedPages;
+			await maybeSyncSearchIndex(adapter, search, {
+				pages: syncPages,
+				documents: buildDocsSearchDocuments(syncPages, search.chunking, "human"),
+				audience: "human",
+				locale: options.locale,
+				pathname: options.pathname,
+				siteTitle: options.siteTitle,
+				baseUrl: indexBaseUrl,
+				indexBaseUrl,
+				...options.paginated && requireCurrentIndexGeneration ? { indexGeneration: await getHostedIndexGeneration() } : {},
+				chunking: search.chunking,
+				signal: options.signal
+			});
+		}
+		if (options.paginated && requireCurrentIndexGeneration) context.indexGeneration = await getHostedIndexGeneration();
+		if (options.paginated && search.provider === "custom" && (!adapter.searchPage || search.raw?.provider !== "custom" || !search.raw.paginationRevision?.trim())) {
+			if (options.paginationMode === "provider") throw new DocsPaginationCursorError();
+			return createLocalPage();
+		}
+		const adapterSearch = options.paginated && adapter.searchPage ? adapter.searchPage(query, context) : adapter.search(query, context);
+		let documents;
+		try {
+			documents = getDocuments();
+		} catch (error) {
+			adapterSearch.catch(() => void 0);
+			throw error;
+		}
+		const rawAdapterResult = await adapterSearch;
+		const adapterPage = options.paginated && !adapter.searchPage && Array.isArray(rawAdapterResult) ? {
+			results: rawAdapterResult.slice(options.offset ?? 0, (options.offset ?? 0) + (query.limit ?? search.maxResults)),
+			total: rawAdapterResult.length
+		} : normalizeDocsSearchAdapterPage(rawAdapterResult);
+		const results = adapterPage.results;
+		if (search.provider === "simple") {
+			if (options.expectedTotal !== void 0 && adapterPage.total !== options.expectedTotal) throw new DocsPaginationCursorError();
+			return {
+				results: await finalizeResults(results, "lexical"),
+				total: options.paginated ? adapterPage.total : results.length,
+				paginationMode: "local"
+			};
+		}
+		const localAudienceProjectionResults = buildAudienceProjectionSearchResults(documents, options.query);
+		const localPagePaths = new Set(scopedPages.map((page) => normalizeUrlRouteKey(page.url)));
+		const allLocalPagePaths = hasFilters && search.provider === "mcp" ? new Set(options.pages.map((page) => normalizeUrlRouteKey(page.url))) : localPagePaths;
+		const preserveUnmatched = !hasFilters && audience === "human" || search.provider === "mcp" ? (result) => shouldPreserveUnmatchedExternalResult({
+			result,
+			localPagePaths: allLocalPagePaths,
+			baseUrl: options.baseUrl
+		}) : void 0;
+		const isKnownLocalProviderResult = (result) => isLocalProviderResult(result, options.baseUrl) && localPagePaths.has(normalizeUrlRouteKey(result.url));
+		const expectedProviderGeneration = requireCurrentIndexGeneration ? await getHostedIndexGeneration() : void 0;
+		const providerAudience = requireCurrentIndexGeneration ? "human" : audience;
+		const safeAdapterResults = sanitizeExternalAudienceSearchResults(results.filter((result) => {
+			if (result.source === void 0) return !requireCurrentIndexGeneration || isKnownLocalProviderResult(result);
+			const source = parseDocsRetrievalSource(result.source, { allowRootRelativeCanonical: requireCurrentIndexGeneration || isKnownLocalProviderResult(result) });
+			const knownLocal = isKnownLocalProviderResult(result);
+			return Boolean(source && docsRetrievalSourceMatchesRequest(source, providerAudience, knownLocal ? void 0 : filters, options.locale) && (!expectedProviderGeneration || source.indexGeneration === expectedProviderGeneration));
+		}).filter((result) => requireCurrentIndexGeneration && isKnownLocalProviderResult(result) || !hasOppositeAudienceEvidence({
+			result,
+			pages: scopedPages,
+			query: options.query,
+			audience,
+			baseUrl: options.baseUrl
+		})), localAudienceProjectionResults, options.baseUrl, preserveUnmatched, requireCurrentIndexGeneration && audience === "agent");
+		if (options.paginated) {
+			const endOffset = (query.offset ?? 0) + safeAdapterResults.length;
+			if (safeAdapterResults.length !== results.length || safeAdapterResults.length > (query.limit ?? search.maxResults) || endOffset > adapterPage.total || requireCurrentIndexGeneration && adapterPage.total === 0 && localAudienceProjectionResults.length > 0 || endOffset < adapterPage.total && safeAdapterResults.length === 0 || adapterPage.nextCursor !== void 0 && options.providerCursor !== void 0 && adapterPage.nextCursor === options.providerCursor || adapterPage.nextCursor !== void 0 && endOffset >= adapterPage.total || options.expectedTotal !== void 0 && adapterPage.total !== options.expectedTotal) return fallBackFromProvider();
+			return {
+				results: await finalizeResults(safeAdapterResults, "provider"),
+				total: adapterPage.total,
+				...adapterPage.nextCursor !== void 0 ? { nextCursor: adapterPage.nextCursor } : {},
+				paginationMode: "provider"
+			};
+		}
+		if (options.supplementExternalResults === false) {
+			const bounded = safeAdapterResults.slice(0, query.limit ?? search.maxResults ?? DEFAULT_SEARCH_LIMIT);
+			return {
+				results: await finalizeResults(bounded, "provider"),
+				total: bounded.length,
+				paginationMode: "provider"
+			};
+		}
+		const simpleAudienceResults = audience === "agent" || results.length === 0 || safeAdapterResults.length < results.length ? await createSimpleSearchAdapter().search(query, context) : [];
+		const exactPageResults = buildExactPageSearchResults(options.query, scopedPages, audience);
+		const rankingStrategyByResult = /* @__PURE__ */ new Map();
+		for (const [group, strategy] of [
+			[exactPageResults, "exact"],
+			[safeAdapterResults, "provider"],
+			[simpleAudienceResults, "lexical"]
+		]) for (const result of group) {
+			const identity = getDocsSearchExplanationResultIdentity(result);
+			if (!rankingStrategyByResult.has(identity)) rankingStrategyByResult.set(identity, strategy);
+		}
+		const combinedResults = mergeSearchResults([
+			exactPageResults,
+			safeAdapterResults,
+			simpleAudienceResults
+		], audience === "agent" ? (result) => getAskAIResultKey(result, options.baseUrl, options.strictExternalOrigins) : void 0);
+		const bounded = prioritizeLiteralInsideResults(options.query, combinedResults).slice(0, query.limit ?? search.maxResults ?? DEFAULT_SEARCH_LIMIT);
+		return {
+			results: await finalizeResults(bounded, (result) => rankingStrategyByResult.get(getDocsSearchExplanationResultIdentity(result)) ?? "provider"),
+			total: bounded.length,
+			paginationMode: "provider"
+		};
+	} catch (error) {
+		if (error instanceof DocsPaginationCursorError) throw error;
+		if (options.failureMode === "throw") throw error;
+		return fallBackFromProvider();
+	}
+}
+async function performDocsSearch(options) {
+	return (await performDocsSearchInternal(options)).results;
+}
+function compareSearchMetadataValues(left, right) {
+	if (left === right) return 0;
+	return left < right ? -1 : 1;
+}
+function docsSearchPageMatchesFacetFilters(scope, filters, omittedField) {
+	if (scope.conflicts.length > 0) return false;
+	return SEARCH_FILTER_FIELDS.every((field) => {
+		if (field === omittedField) return true;
+		const requested = filters[field];
+		return !requested?.length || docsSearchScopeFieldMatches(scope, field, requested);
+	});
+}
+function buildDocsSearchFacet(pages, field, filters, options) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const { scope } of pages) {
+		if (!docsSearchPageMatchesFacetFilters(scope, filters, field)) continue;
+		for (const value of new Set(scope[field])) counts.set(value, (counts.get(value) ?? 0) + 1);
+	}
+	const values = [...counts].sort(([left], [right]) => compareSearchMetadataValues(left, right)).map(([value, count]) => ({
+		value,
+		count
+	}));
+	const normalizedFilters = Object.fromEntries(SEARCH_FILTER_FIELDS.flatMap((filterField) => {
+		const filterValues = filters[filterField];
+		return filterValues?.length ? [[filterField, [...filterValues].sort(compareSearchMetadataValues)]] : [];
+	}));
+	const page = paginateDocsItems(values, {
+		kind: "docs-search-facet",
+		scope: JSON.stringify({
+			format: "docs-search-facet-pagination.v1",
+			field,
+			audience: options.audience,
+			filters: normalizedFilters,
+			locale: options.locale ? normalizeAgentLocale(options.locale) : void 0
+		}),
+		snapshot: options.indexGeneration,
+		cursor: options.cursor,
+		pageSize: options.limit
+	});
+	return {
+		valueCount: page.total,
+		total: page.total,
+		hasMore: page.hasMore,
+		...page.nextCursor ? { nextCursor: page.nextCursor } : {},
+		truncated: page.items.length < page.total,
+		values: page.items
+	};
+}
+/**
+* Build a body-free index of valid search filter values and page counts.
+*
+* Each facet applies filters from the other fields while ignoring its own selected
+* values. This is the conventional faceted-search behavior and lets an agent discover
+* safe alternatives without guessing or fetching document bodies.
+*/
+async function buildDocsSearchFacets(options) {
+	const audience = resolveDocsSearchAudience(options.audience);
+	const filters = normalizeDocsSearchFilters(options.filters);
+	const search = normalizeDocsSearchConfig(options.search);
+	const requestedLimit = options.limit ?? MAX_SEARCH_FACET_VALUES;
+	if (!Number.isSafeInteger(requestedLimit) || requestedLimit < 1 || requestedLimit > MAX_SEARCH_FACET_VALUES) throw new DocsSearchRequestError("Search limit must be an integer between 1 and 100.");
+	if (options.cursor !== void 0 && options.facet === void 0) throw new DocsSearchRequestError("Facet continuation cursors require a `facet` field.");
+	const accessiblePages = filterDocsPagesByAccess(options.pages, options.principal);
+	const pages = accessiblePages.map((page) => localizeDocsSearchPage(page, options.locale)).map((page) => ({ scope: resolveDocsSearchPageScope(page) }));
+	const indexGeneration = options.indexGeneration ?? await buildDocsSearchIndexGeneration(accessiblePages, {
+		audience,
+		chunking: search.chunking,
+		locale: options.locale,
+		baseUrl: options.baseUrl
+	});
+	return {
+		format: "docs-search-facets.v1",
+		audience,
+		filters,
+		indexGeneration,
+		matchedPageCount: pages.filter(({ scope }) => docsSearchPageMatchesFacetFilters(scope, filters)).length,
+		facets: Object.fromEntries(SEARCH_FILTER_FIELDS.map((field) => [field, buildDocsSearchFacet(pages, field, filters, {
+			audience,
+			cursor: field === options.facet ? options.cursor : void 0,
+			indexGeneration,
+			limit: options.facet === void 0 || field === options.facet ? requestedLimit : MAX_SEARCH_FACET_VALUES,
+			locale: options.locale
+		})]))
+	};
+}
+function boundedSearchWarningValues(values) {
+	const bounded = Array.from(new Set(values)).sort(compareSearchMetadataValues).slice(0, MAX_SEARCH_WARNING_VALUES);
+	return bounded.length > 0 ? bounded : void 0;
+}
+function boundedSearchWarningPageUrls(pages) {
+	const bounded = Array.from(new Set(pages.map((page) => page.url))).sort(compareSearchMetadataValues).slice(0, MAX_SEARCH_WARNING_PAGE_URLS);
+	return bounded.length > 0 ? bounded : void 0;
+}
+function findSearchResultPages(pages, results, baseUrl) {
+	const pagesByPath = new Map(pages.map((page) => [normalizeUrlRouteKey(page.url), page]));
+	const found = /* @__PURE__ */ new Map();
+	for (const result of results) {
+		if (!isLocalProviderResult(result, baseUrl)) continue;
+		const page = pagesByPath.get(normalizeUrlRouteKey(result.url));
+		if (page) found.set(page.url, page);
+	}
+	return [...found.values()].sort((left, right) => compareSearchMetadataValues(left.url, right.url));
+}
+function searchScopeIsAmbiguous(field, values) {
+	if (values.length < 2) return false;
+	if (field !== "version") return true;
+	return values.some((left, index) => values.slice(index + 1).some((right) => !agentVersionConstraintsOverlap(left, right)));
+}
+function buildDocsSearchWarnings(options) {
+	const pageScopes = options.pages.map((page) => ({
+		page,
+		scope: resolveDocsSearchPageScope(page)
+	}));
+	const relevantPageScopes = pageScopes.filter(({ page }) => scoreDocument(options.query, pageToSearchDocument(page, options.audience)) > 0);
+	const warnings = [];
+	for (const field of SEARCH_FILTER_FIELDS) {
+		const conflicting = relevantPageScopes.filter(({ scope }) => scope.conflicts.includes(field));
+		if (conflicting.length > 0) warnings.push({
+			code: "conflicting_scope_metadata",
+			field,
+			message: `${conflicting.length} page${conflicting.length === 1 ? "" : "s"} declare conflicting ${field} metadata and cannot be selected safely by scoped search.`,
+			pageUrls: boundedSearchWarningPageUrls(conflicting.map(({ page }) => page)),
+			count: conflicting.length
+		});
+		const requested = options.filters[field];
+		if (!requested || requested.length === 0) continue;
+		const missing = relevantPageScopes.filter(({ scope }) => scope.declarations[field].length === 0);
+		if (missing.length > 0) warnings.push({
+			code: "missing_scope_metadata",
+			field,
+			message: `${missing.length} page${missing.length === 1 ? "" : "s"} lack ${field} metadata and were excluded by the strict scope filter.`,
+			pageUrls: boundedSearchWarningPageUrls(missing.map(({ page }) => page)),
+			count: missing.length
+		});
+		const unknown = requested.filter((value) => !pageScopes.some(({ scope }) => !scope.conflicts.includes(field) && docsSearchScopeFieldMatches(scope, field, [value])));
+		if (unknown.length > 0) warnings.push({
+			code: "unknown_filter_value",
+			field,
+			message: `No page metadata matches ${field} filter value${unknown.length === 1 ? "" : "s"}: ${unknown.join(", ")}.`,
+			values: boundedSearchWarningValues(unknown),
+			count: unknown.length
+		});
+	}
+	const resultPages = options.completeResultSet ? relevantPageScopes.filter(({ scope }) => docsSearchPageMatchesFilters(scope, options.filters)).map(({ page }) => page).sort((left, right) => compareSearchMetadataValues(left.url, right.url)) : findSearchResultPages(options.pages, options.results, options.baseUrl);
+	for (const field of SEARCH_AMBIGUITY_FIELDS) {
+		if ((options.filters[field]?.length ?? 0) > 0) continue;
+		const values = resultPages.flatMap((page) => {
+			const scope = resolveDocsSearchPageScope(page);
+			return scope.conflicts.includes(field) ? [] : scope[field];
+		});
+		const unique = Array.from(new Set(values)).sort(compareSearchMetadataValues);
+		if (!searchScopeIsAmbiguous(field, unique)) continue;
+		const contributingPages = resultPages.filter((page) => {
+			const scope = resolveDocsSearchPageScope(page);
+			return !scope.conflicts.includes(field) && scope[field].length > 0;
+		});
+		warnings.push({
+			code: "ambiguous_scope",
+			field,
+			message: `Search results span multiple ${field} scopes; add a ${field} filter before acting on scope-specific guidance.`,
+			values: boundedSearchWarningValues(unique),
+			pageUrls: boundedSearchWarningPageUrls(contributingPages),
+			count: unique.length
+		});
+	}
+	const codeOrder = {
+		ambiguous_scope: 0,
+		unknown_filter_value: 1,
+		missing_scope_metadata: 2,
+		conflicting_scope_metadata: 3
+	};
+	return warnings.sort((left, right) => {
+		const codeDelta = codeOrder[left.code] - codeOrder[right.code];
+		if (codeDelta !== 0) return codeDelta;
+		return SEARCH_FILTER_FIELDS.indexOf(left.field) - SEARCH_FILTER_FIELDS.indexOf(right.field);
+	}).slice(0, MAX_SEARCH_WARNINGS);
+}
+function parseDocsSearchCursorState(state, offset) {
+	if (offset === 0 && state === void 0) return void 0;
+	if (state === void 0) throw new DocsPaginationCursorError();
+	let parsed;
+	try {
+		parsed = JSON.parse(state);
+	} catch {
+		throw new DocsPaginationCursorError();
+	}
+	if (!Array.isArray(parsed) || parsed.length !== 4 || JSON.stringify(parsed) !== state) throw new DocsPaginationCursorError();
+	const [version, mode, total, providerCursor] = parsed;
+	if (version !== 1 || mode !== "local" && mode !== "provider" || !Number.isSafeInteger(total) || total < offset || !(providerCursor === null || typeof providerCursor === "string" && providerCursor.length <= 768) || mode === "local" && providerCursor !== null) throw new DocsPaginationCursorError();
+	return {
+		mode,
+		total,
+		...typeof providerCursor === "string" ? { providerCursor } : {}
+	};
+}
+function createDocsSearchCursorState(page) {
+	return JSON.stringify([
+		1,
+		page.paginationMode,
+		page.total,
+		page.paginationMode === "provider" ? page.nextCursor ?? null : null
+	]);
+}
+async function performDocsSearchWithMetadata(options) {
+	const audience = resolveDocsSearchAudience(options.audience);
+	const filters = normalizeDocsSearchFilters(options.filters);
+	const search = normalizeDocsSearchConfig(options.search);
+	const requestedLimit = options.limit ?? search.maxResults ?? DEFAULT_SEARCH_LIMIT;
+	const limit = Number.isFinite(requestedLimit) && requestedLimit > 0 ? Math.max(1, Math.floor(requestedLimit)) : DEFAULT_SEARCH_LIMIT;
+	const indexGeneration = options.indexGeneration ?? await buildDocsSearchIndexGeneration(filterDocsPagesByAccess(options.generationPages ?? options.pages, options.principal), {
+		audience,
+		chunking: search.chunking,
+		locale: options.locale,
+		baseUrl: options.baseUrl
+	});
+	const normalizedFilters = Object.fromEntries(SEARCH_FILTER_FIELDS.flatMap((field) => {
+		const values = filters[field];
+		return values?.length ? [[field, [...values].sort(compareSearchMetadataValues)]] : [];
+	}));
+	const provider = getDocsSearchPaginationProviderIdentity(search);
+	const cursorOptions = {
+		kind: "docs-search",
+		scope: JSON.stringify({
+			format: "docs-search-pagination.v2",
+			query: options.query,
+			audience,
+			filters: normalizedFilters,
+			locale: options.locale ? normalizeAgentLocale(options.locale) : void 0,
+			pathname: options.pathname?.trim() || void 0,
+			provider,
+			limit
+		}),
+		snapshot: indexGeneration
+	};
+	const cursorPosition = resolveDocsPaginationCursor(options.cursor, cursorOptions);
+	const offset = cursorPosition.offset;
+	const cursorState = parseDocsSearchCursorState(cursorPosition.state, offset);
+	const page = options.query.trim() ? await performDocsSearchInternal({
+		...options,
+		audience,
+		filters,
+		indexGeneration,
+		limit,
+		offset,
+		paginated: true,
+		providerCursor: cursorState?.providerCursor,
+		paginationMode: cursorState?.mode,
+		expectedTotal: cursorState?.total
+	}) : {
+		results: [],
+		total: 0,
+		paginationMode: "local"
+	};
+	if (options.cursor !== void 0 && offset >= page.total || page.results.length > Math.min(limit, Math.max(0, page.total - offset)) || offset < page.total && page.results.length === 0) throw new DocsPaginationCursorError();
+	const nextOffset = Math.min(page.total, offset + page.results.length);
+	const hasMore = nextOffset < page.total;
+	const nextCursor = hasMore ? createDocsPaginationCursor(nextOffset, {
+		...cursorOptions,
+		state: createDocsSearchCursorState(page)
+	}) : void 0;
+	return {
+		format: "docs-search.v1",
+		query: options.query,
+		audience,
+		filters,
+		indexGeneration,
+		resultCount: page.results.length,
+		total: page.total,
+		hasMore,
+		...nextCursor ? { nextCursor } : {},
+		results: page.results,
+		warnings: buildDocsSearchWarnings({
+			pages: options.pages,
+			results: page.results,
+			filters,
+			query: options.query,
+			audience,
+			baseUrl: options.baseUrl,
+			completeResultSet: true
+		})
+	};
+}
+async function buildDocsAskAIContext(options) {
+	const limit = options.limit ?? 5;
+	const searchLimit = Math.max(limit * 2, limit);
+	const initialSearch = options.search === false ? true : options.search;
+	const primarySearch = normalizeDocsSearchConfig(initialSearch).enabled ? initialSearch : true;
+	const searchResults = await performDocsSearch({
+		pages: options.pages,
+		query: options.query,
+		search: primarySearch,
+		audience: "agent",
+		locale: options.locale,
+		pathname: options.pathname,
+		siteTitle: options.siteTitle,
+		baseUrl: options.baseUrl,
+		syncBaseUrl: options.syncBaseUrl,
+		limit: searchLimit,
+		filters: options.filters,
+		failureMode: options.searchFailureMode,
+		strictExternalOrigins: options.strictExternalOrigins,
+		signal: options.signal
+	});
+	const seen = /* @__PURE__ */ new Set();
+	const maxResultChars = options.maxResultChars ?? DEFAULT_ASK_AI_RESULT_CHARS;
+	const rankedResults = searchResults.map((result, index) => {
+		const formatted = formatAskAIContextResult({
+			result,
+			page: findPageForSearchResult(options.pages, result, options.baseUrl),
+			maxChars: maxResultChars,
+			baseUrl: options.baseUrl
+		});
+		return {
+			result,
+			formatted,
+			index,
+			rank: rankAskAIContextResult(options.query, formatted)
+		};
+	}).sort((a, b) => b.rank - a.rank || a.index - b.index);
+	const formattedResults = rankedResults.map((item) => item.formatted);
+	const sectionResultPaths = new Set(formattedResults.filter((result) => result.section).map((result) => getAskAIResultPageKey(result.url, options.baseUrl, options.strictExternalOrigins)));
+	const results = formattedResults.filter((result) => result.section || !sectionResultPaths.has(getAskAIResultPageKey(result.url, options.baseUrl, options.strictExternalOrigins))).filter((result) => {
+		const key = getAskAIResultKey(result, options.baseUrl, options.strictExternalOrigins);
+		if (seen.has(key)) return false;
+		seen.add(key);
+		return result.contextContent.length > 0;
+	}).slice(0, limit);
+	const maxContextChars = options.maxContextChars ?? DEFAULT_ASK_AI_CONTEXT_CHARS;
+	const blocks = [];
+	let usedChars = 0;
+	for (const result of results) {
+		const block = buildAskAIContextBlock(result);
+		const separatorChars = blocks.length === 0 ? 0 : 7;
+		if (usedChars + separatorChars + block.length > maxContextChars) {
+			const remaining = maxContextChars - usedChars - separatorChars;
+			if (remaining > 400) blocks.push(clampText(block, remaining));
+			break;
+		}
+		blocks.push(block);
+		usedChars += separatorChars + block.length;
+	}
+	const context = blocks.join("\n\n---\n\n");
+	return {
+		context,
+		blocks: blocks.map((text, index) => ({
+			text,
+			result: results[index]
+		})),
+		results: results.slice(0, blocks.length),
+		searchResults: rankedResults.map((item) => item.result),
+		packageHints: inferDocsAskAIPackageHints(context)
+	};
+}
+function createCustomSearchAdapter(adapter, options = {}) {
+	return {
+		provider: "custom",
+		adapter,
+		...options.paginationRevision ? { paginationRevision: options.paginationRevision } : {}
+	};
+}
+
+//#endregion
+export { DocsSearchRequestError, buildDocsAskAIContext, buildDocsContentSnapshot, buildDocsRetrievalDigestProjection, buildDocsSearchDocuments, buildDocsSearchFacets, createAlgoliaSearchAdapter, createCustomSearchAdapter, createMcpSearchAdapter, createSimpleSearchAdapter, createTypesenseSearchAdapter, enrichDocsSearchDocumentsWithProvenance, formatDocsAskAIPackageHints, inferDocsAskAIPackageHints, normalizeDocsSearchFilters, performDocsSearch, performDocsSearchWithMetadata, resolveAskAISearchRequestConfig, resolveDocsRetrievalLastModified, resolveDocsSearchAudience, resolveDocsSearchError, resolveDocsSearchFilters, resolveDocsSearchRequest, resolveLocalDocsMcpSearchConfig, resolveSearchRequestConfig };