@farming-labs/docs 0.2.73 → 0.2.74

package/dist/{search-RfPcG1if.mjs → search-DIyIl-tE.mjs}

@@ -1,4 +1,4 @@
-import { G as isDocsAgentDiscoveryRequest, K as isDocsAgentsRequest, Q as isDocsSkillRequest, _t as resolveDocsMarkdownRequest, dt as resolveDocsAgentsFormat, jt as resolveDocsAudienceMdxContent, lt as resolveDocsAgentFeedbackConfig, pt as resolveDocsLlmsTxtRequest, ut as resolveDocsAgentFeedbackRequest, xt as resolveDocsSkillFormat } from "./agent-o9OTadrf.mjs";
+import { G as isDocsAgentDiscoveryRequest, K as isDocsAgentsRequest, Q as isDocsSkillRequest, _t as resolveDocsMarkdownRequest, dt as resolveDocsAgentsFormat, jt as resolveDocsAudienceMdxContent, lt as resolveDocsAgentFeedbackConfig, pt as resolveDocsLlmsTxtRequest, ut as resolveDocsAgentFeedbackRequest, xt as resolveDocsSkillFormat } from "./agent-BJ0KXN-A.mjs";
 import { S as upsertPageAgentContractMarkdown, a as findDocsGeneratedAgentContractRanges, d as PAGE_AGENT_CONTRACT_END_MARKER, l as stripDocsGeneratedAgentContractMarkers, m as PAGE_AGENT_CONTRACT_START_MARKER, o as findDocsMarkdownSection, s as parseDocsMarkdownSections, y as renderPageAgentContractMarkdown } from "./markdown-sections-7OoA7ylx.mjs";
 
 //#region src/telemetry.ts
@@ -458,6 +458,172 @@ function serializeGeneratedAgentDocument(content, provenance) {
 	].join("\n")}\n`;
 }
 
+//#endregion
+//#region src/retrieval-digest.ts
+const SHA256_INITIAL_STATE = [
+	1779033703,
+	3144134277,
+	1013904242,
+	2773480762,
+	1359893119,
+	2600822924,
+	528734635,
+	1541459225
+];
+const SHA256_ROUND_CONSTANTS = [
+	1116352408,
+	1899447441,
+	3049323471,
+	3921009573,
+	961987163,
+	1508970993,
+	2453635748,
+	2870763221,
+	3624381080,
+	310598401,
+	607225278,
+	1426881987,
+	1925078388,
+	2162078206,
+	2614888103,
+	3248222580,
+	3835390401,
+	4022224774,
+	264347078,
+	604807628,
+	770255983,
+	1249150122,
+	1555081692,
+	1996064986,
+	2554220882,
+	2821834349,
+	2952996808,
+	3210313671,
+	3336571891,
+	3584528711,
+	113926993,
+	338241895,
+	666307205,
+	773529912,
+	1294757372,
+	1396182291,
+	1695183700,
+	1986661051,
+	2177026350,
+	2456956037,
+	2730485921,
+	2820302411,
+	3259730800,
+	3345764771,
+	3516065817,
+	3600352804,
+	4094571909,
+	275423344,
+	430227734,
+	506948616,
+	659060556,
+	883997877,
+	958139571,
+	1322822218,
+	1537002063,
+	1747873779,
+	1955562222,
+	2024104815,
+	2227730452,
+	2361852424,
+	2428436474,
+	2756734187,
+	3204031479,
+	3329325298
+];
+function rotateRight(value, bits) {
+	return value >>> bits | value << 32 - bits;
+}
+function normalizeDigestContent(value) {
+	return value.replace(/\r\n?/gu, "\n").replace(/^\uFEFF/u, "").trimEnd();
+}
+/** Validate the bounded HTTP(S) URL or root-relative URI reference used by provenance. */
+function isDocsRetrievalCanonicalUrl(value) {
+	const hasUnsafeCharacter = value.includes("\\") || Array.from(value).some((character) => {
+		const codePoint = character.codePointAt(0) ?? 0;
+		return codePoint <= 31 || codePoint === 127;
+	});
+	if (!value || value !== value.trim() || value.length > 4096 || hasUnsafeCharacter) return false;
+	if (/^\/(?!\/)/u.test(value)) try {
+		new URL(value, "https://docs.local");
+		return true;
+	} catch {
+		return false;
+	}
+	try {
+		const url = new URL(value);
+		return (url.protocol === "http:" || url.protocol === "https:") && !url.username && !url.password;
+	} catch {
+		return false;
+	}
+}
+/**
+* Hash a retrieval source projection with portable SHA-256.
+*
+* The projection is normalized by removing one leading BOM, converting CRLF/CR
+* line endings to LF, and trimming trailing whitespace. The helper is exported so
+* agents can independently verify provenance in Node, edge, and browser runtimes.
+*/
+function digestDocsRetrievalContent(value) {
+	const input = new TextEncoder().encode(normalizeDigestContent(value));
+	const paddedLength = Math.ceil((input.length + 9) / 64) * 64;
+	const padded = new Uint8Array(paddedLength);
+	padded.set(input);
+	padded[input.length] = 128;
+	const bitLength = input.length * 8;
+	const dataView = new DataView(padded.buffer);
+	dataView.setUint32(paddedLength - 8, Math.floor(bitLength / 4294967296), false);
+	dataView.setUint32(paddedLength - 4, bitLength >>> 0, false);
+	const state = Uint32Array.from(SHA256_INITIAL_STATE);
+	const words = new Uint32Array(64);
+	for (let offset = 0; offset < padded.length; offset += 64) {
+		for (let index = 0; index < 16; index += 1) words[index] = dataView.getUint32(offset + index * 4, false);
+		for (let index = 16; index < 64; index += 1) {
+			const previous15 = words[index - 15];
+			const previous2 = words[index - 2];
+			const sigma0 = rotateRight(previous15, 7) ^ rotateRight(previous15, 18) ^ previous15 >>> 3;
+			const sigma1 = rotateRight(previous2, 17) ^ rotateRight(previous2, 19) ^ previous2 >>> 10;
+			words[index] = words[index - 16] + sigma0 + words[index - 7] + sigma1 >>> 0;
+		}
+		let a = state[0];
+		let b = state[1];
+		let c = state[2];
+		let d = state[3];
+		let e = state[4];
+		let f = state[5];
+		let g = state[6];
+		let h = state[7];
+		for (let index = 0; index < 64; index += 1) {
+			const sum1 = rotateRight(e, 6) ^ rotateRight(e, 11) ^ rotateRight(e, 25);
+			const choice = e & f ^ ~e & g;
+			const temporary1 = h + sum1 + choice + SHA256_ROUND_CONSTANTS[index] + words[index] >>> 0;
+			const temporary2 = (rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22)) + (a & b ^ a & c ^ b & c) >>> 0;
+			h = g;
+			g = f;
+			f = e;
+			e = d + temporary1 >>> 0;
+			d = c;
+			c = b;
+			b = a;
+			a = temporary1 + temporary2 >>> 0;
+		}
+		state[0] = state[0] + a >>> 0;
+		state[1] = state[1] + b >>> 0;
+		state[2] = state[2] + c >>> 0;
+		state[3] = state[3] + d >>> 0;
+		state[4] = state[4] + e >>> 0;
+		state[5] = state[5] + f >>> 0;
+		state[6] = state[6] + g >>> 0;
+		state[7] = state[7] + h >>> 0;
+	}
+	return `sha256:${Array.from(state, (word) => word.toString(16).padStart(8, "0")).join("")}`;
+}
+
 //#endregion
 //#region src/agent-scope.ts
 /** Normalize framework aliases used by page metadata, agent contracts, MCP, and evaluations. */
@@ -784,7 +950,8 @@ const DEFAULT_SEARCH_LIMIT = 10;
 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 Set();
+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;
@@ -794,9 +961,13 @@ const MAX_SEARCH_FILTER_RAW_CHARS = 4096;
 const MAX_SEARCH_FILTER_SEGMENTS = 64;
 const MAX_PROVIDER_SCOPE_FILTER_IDS = 1e3;
 const MAX_PROVIDER_SCOPE_FILTER_CHARS = 16e3;
+const ALGOLIA_BATCH_OPERATIONS = 1e3;
 const MAX_SEARCH_WARNINGS = 16;
 const MAX_SEARCH_WARNING_VALUES = 16;
 const MAX_SEARCH_WARNING_PAGE_URLS = 8;
+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",
@@ -896,9 +1067,10 @@ function resolveDocsSearchRequest(searchParams) {
 function hasDocsSearchFilters(filters) {
 	return SEARCH_FILTER_FIELDS.some((field) => (filters[field]?.length ?? 0) > 0);
 }
-function resolveProviderScopeDocumentIds(query, context) {
+function resolveProviderScopeDocumentIds(query, context, corpusId) {
 	if (!hasDocsSearchFilters(query.filters ?? {})) return void 0;
-	const ids = Array.from(new Set(context.documents.map((document) => document.id)));
+	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 : [];
 }
 function docsSearchFiltersMatch(expected, actual) {
@@ -1011,13 +1183,49 @@ function isLiteralLookupQuery(query) {
 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 normalizeUrlPathname(value) {
+function normalizeUrlRouteKey(value) {
 	try {
-		return new URL(value, "https://docs.local").pathname.replace(/\/+$/, "") || "/";
+		const url = new URL(value, "https://docs.local");
+		return `${url.pathname || "/"}${url.search}`;
 	} catch {
-		return value.split(/[?#]/)[0]?.replace(/\/+$/, "") || "/";
+		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);
@@ -1129,19 +1337,19 @@ function clampText(value, maxChars) {
 	if (value.length <= maxChars) return value;
 	return `${value.slice(0, maxChars).trimEnd()}...`;
 }
-function findPageForSearchResult(pages, result, baseUrl, strictExternalOrigins = false) {
+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 && strictExternalOrigins) 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 = normalizeUrlPathname(result.url);
-	return pages.find((page) => normalizeUrlPathname(page.url) === resultPath);
+	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;
@@ -1163,7 +1371,7 @@ function formatAskAIContextResult(options) {
 function getSearchResultKey(result) {
 	const anchor = getSearchResultAnchor(result.url);
 	const sectionFallback = normalizeWhitespace(result.section ?? "").toLowerCase();
-	return `${normalizeUrlPathname(result.url)}#${anchor ?? sectionFallback}`;
+	return `${normalizeUrlRouteKey(result.url)}#${anchor ?? sectionFallback}`;
 }
 function getSearchResultAnchor(value) {
 	let hash = "";
@@ -1181,7 +1389,7 @@ function getSearchResultAnchor(value) {
 	}
 }
 function getAskAIResultPageKey(value, baseUrl, strictExternalOrigins = false) {
-	const path = normalizeUrlPathname(value);
+	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 {
@@ -1224,11 +1432,11 @@ function buildAudienceProjectionSearchResults(documents, query) {
 		};
 	});
 }
-function sanitizeExternalAudienceSearchResults(results, localAudienceResults, baseUrl, strictExternalOrigins = false, preserveUnmatched) {
+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 = normalizeUrlPathname(result.url);
+		const pageUrl = normalizeUrlRouteKey(result.url);
 		if (!localPageResults.get(pageUrl) || result.type === "page") localPageResults.set(pageUrl, result);
 	}
 	return results.flatMap((result) => {
@@ -1236,7 +1444,7 @@ function sanitizeExternalAudienceSearchResults(results, localAudienceResults, ba
 		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 || !baseUrl && !strictExternalOrigins;
+		let sameOriginOrUnknown = !externallyHosted;
 		if (unsupportedScheme) sameOriginOrUnknown = false;
 		if (externallyHosted && baseUrl) try {
 			sameOriginOrUnknown = new URL(result.url, baseUrl).origin === new URL(baseUrl).origin;
@@ -1244,7 +1452,7 @@ function sanitizeExternalAudienceSearchResults(results, localAudienceResults, ba
 			sameOriginOrUnknown = false;
 		}
 		const hasSection = Boolean(getSearchResultAnchor(result.url) || result.section);
-		const local = sameOriginOrUnknown ? localByKey.get(getSearchResultKey(result)) ?? (hasSection ? void 0 : localPageResults.get(normalizeUrlPathname(result.url))) : void 0;
+		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,
@@ -1255,14 +1463,14 @@ function sanitizeExternalAudienceSearchResults(results, localAudienceResults, ba
 }
 function shouldPreserveUnmatchedExternalResult(options) {
 	const { result, localPagePaths, baseUrl } = options;
-	const path = normalizeUrlPathname(result.url);
+	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 !knownLocalPath;
+	if (!baseUrl) return true;
 	try {
 		if (new URL(result.url, baseUrl).origin !== new URL(baseUrl).origin) return true;
 	} catch {
@@ -1270,22 +1478,526 @@ function shouldPreserveUnmatchedExternalResult(options) {
 	}
 	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(audience === "agent" ? page.agentRawContent ?? page.agentFallbackRawContent ?? page.agentContent ?? page.agentFallbackContent ?? page.rawContent ?? page.content : page.rawContent ?? page.content, 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 isLocalProviderResult(result, baseUrl, strictExternalOrigins = false) {
+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
+	}));
+}
+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,
+			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 !strictExternalOrigins;
+	if (!baseUrl) return false;
 	try {
 		return new URL(result.url, baseUrl).origin === new URL(baseUrl).origin;
 	} catch {
@@ -1293,10 +2005,10 @@ function isLocalProviderResult(result, baseUrl, strictExternalOrigins = false) {
 	}
 }
 function hasOppositeAudienceEvidence(options) {
-	const { result, pages, query, audience, baseUrl, strictExternalOrigins } = options;
-	if (!isLocalProviderResult(result, baseUrl, strictExternalOrigins)) return false;
-	const pagePath = normalizeUrlPathname(result.url);
-	const page = pages.find((candidate) => normalizeUrlPathname(candidate.url) === pagePath);
+	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";
@@ -1316,13 +2028,14 @@ function hasOppositeAudienceEvidence(options) {
 	}
 	return oppositeOnlyMatches > selectedOnlyMatches;
 }
-function pageToSearchDocument(page, audience = "human") {
+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: normalizeWhitespace([getPageAudienceSearchText(page, audience), getPageAgentContractSearchText(page)].join(" ")),
+		content: getPageAudienceIndexContent(page, audience),
 		description: page.description,
 		type: "page",
 		locale: page.locale,
@@ -1385,6 +2098,23 @@ 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();
 }
@@ -1420,7 +2150,8 @@ function splitPageIntoSections(page, audience = "human") {
 }
 function buildDocsSearchDocuments(pages, chunking = {}, audience = "human") {
 	const strategy = chunking.strategy ?? "section";
-	return pages.flatMap((page) => {
+	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);
@@ -1526,50 +2257,60 @@ function cleanSearchResultText(value) {
 	if (!value) return void 0;
 	return normalizeWhitespace(stripHtml(stripMarkdownText(value))) || void 0;
 }
-function trimTextToBytes(value, maxBytes) {
-	if (maxBytes <= 0) return "";
-	const encoder = new TextEncoder();
-	if (encoder.encode(value).length <= maxBytes) return value;
-	let low = 0;
-	let high = value.length;
-	let best = "";
-	while (low <= high) {
-		const mid = Math.floor((low + high) / 2);
-		const next = `${value.slice(0, mid).trimEnd()}...`;
-		if (encoder.encode(next).length <= maxBytes) {
-			best = next;
-			low = mid + 1;
-		} else high = mid - 1;
-	}
-	return best;
-}
-function buildAlgoliaRecord(document) {
+function buildAlgoliaRecord(document, corpusId) {
+	const providerDocumentId = corpusId ? makeHostedProviderDocumentId(corpusId, document.id) : document.id;
 	const record = {
-		objectID: document.id,
-		id: document.id,
+		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,
+		locale: document.locale ?? document.source?.scope.locale?.[0],
 		framework: document.framework,
 		version: document.version,
 		package: document.package,
-		tags: document.tags
+		tags: document.tags,
+		_tags: corpusId ? [corpusId] : 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;
-	const fixedBytes = sizeOf({
-		...record,
-		content: ""
-	});
-	const remainingBytes = Math.max(ALGOLIA_MAX_RECORD_BYTES - fixedBytes - 32, 0);
-	record.content = trimTextToBytes(document.content, remainingBytes);
+	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;
 }
 function createSimpleSearchAdapter() {
@@ -1577,7 +2318,7 @@ function createSimpleSearchAdapter() {
 		name: "simple",
 		async search(query, context) {
 			const limit = query.limit ?? DEFAULT_SEARCH_LIMIT;
-			return context.documents.map((document) => ({
+			const results = context.documents.map((document) => ({
 				document,
 				score: scoreDocument(query.query, document)
 			})).filter((item) => item.score > 0).sort((a, b) => {
@@ -1590,8 +2331,20 @@ function createSimpleSearchAdapter() {
 				description: cleanSearchResultText(buildSnippet(document, query.query) ?? document.description),
 				type: document.type,
 				score,
-				section: document.section
+				section: document.section,
+				source: document.source
 			}));
+			if (context.deferSourceProvenance) return results;
+			return 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
+			});
 		}
 	};
 }
@@ -1644,7 +2397,7 @@ function resolveMcpEndpoint(endpoint) {
 function isDocsSearchResultType(value) {
 	return value === "page" || value === "heading" || value === "text";
 }
-function mapMcpSearchResult(value) {
+function mapMcpSearchResult(value, sourceBaseUrl) {
 	if (!value || typeof value !== "object") return null;
 	const item = value;
 	const section = typeof item.section === "string" ? item.section : void 0;
@@ -1652,6 +2405,19 @@ function mapMcpSearchResult(value) {
 	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,
@@ -1659,7 +2425,8 @@ function mapMcpSearchResult(value) {
 		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
+		section,
+		...source ? { source } : {}
 	};
 }
 function readMcpSearchToolPayload(payload) {
@@ -1692,7 +2459,84 @@ function getTypesenseSearchBase(config) {
 function quoteTypesenseFilterValue(value) {
 	return `\`${value.replace(/\\/gu, "\\\\").replace(/`/gu, "\\`")}\``;
 }
-async function ensureTypesenseCollection(config, dimensions, signal) {
+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,
@@ -1702,7 +2546,50 @@ async function ensureTypesenseCollection(config, dimensions, signal) {
 		headers,
 		signal
 	});
-	if (existing.ok) return;
+	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 = [
 		{
@@ -1759,7 +2646,8 @@ async function ensureTypesenseCollection(config, dimensions, signal) {
 			name: "tags",
 			type: "string[]",
 			optional: true
-		}
+		},
+		...TYPESENSE_RETRIEVAL_SOURCE_FIELDS
 	];
 	if (config.embeddings && dimensions) fields.push({
 		name: "embedding",
@@ -1767,7 +2655,7 @@ async function ensureTypesenseCollection(config, dimensions, signal) {
 		num_dim: dimensions,
 		optional: true
 	});
-	ensureOk(await fetch(`${baseUrl}/collections`, {
+	const response = await fetch(`${baseUrl}/collections`, {
 		method: "POST",
 		headers,
 		body: JSON.stringify({
@@ -1775,34 +2663,66 @@ async function ensureTypesenseCollection(config, dimensions, signal) {
 			fields
 		}),
 		signal
-	}), "Failed to create Typesense collection");
+	});
+	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) {
 	return {
 		name: "typesense",
 		async index(context) {
 			const adminApiKey = config.adminApiKey ?? config.apiKey;
-			const docsForImport = await Promise.all(context.documents.map(async (document) => {
+			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: document.id,
+					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,
+					locale: document.locale ?? document.source?.scope.locale?.[0],
 					framework: document.framework,
 					version: document.version,
 					package: document.package,
-					tags: document.tags
+					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;
 			}));
-			if (docsForImport.length === 0) return;
 			await ensureTypesenseCollection(config, Array.isArray(docsForImport[0]?.embedding) ? docsForImport[0].embedding.length : void 0, context.signal);
-			ensureOk(await fetch(`${getTypesenseSearchBase(config)}/collections/${encodeURIComponent(config.collection)}/documents/import?action=upsert`, {
+			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,
@@ -1810,10 +2730,11 @@ function createTypesenseSearchAdapter(config) {
 				},
 				body: docsForImport.map((document) => JSON.stringify(document)).join("\n"),
 				signal: context.signal
-			}), "Failed to sync documents to Typesense");
+			}), docsForImport.length);
 		},
 		async search(query, context) {
-			const scopedDocumentIds = resolveProviderScopeDocumentIds(query, context);
+			const corpusId = resolveHostedHumanCorpusId(config.syncNamespace, context);
+			const scopedDocumentIds = resolveProviderScopeDocumentIds(query, context, corpusId);
 			if (scopedDocumentIds?.length === 0) return [];
 			const params = new URLSearchParams({
 				q: query.query,
@@ -1832,7 +2753,8 @@ function createTypesenseSearchAdapter(config) {
 				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 filterBy = scopedDocumentIds ? `id:=[${scopedDocumentIds.map(quoteTypesenseFilterValue).join(",")}]` : void 0;
+			const filterClauses = [corpusId ? `source_corpus_id:=${quoteTypesenseFilterValue(corpusId)}` : 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) return [];
 			const response = filterBy ? await fetch(`${getTypesenseSearchBase(config)}/multi_search`, {
 				method: "POST",
@@ -1852,13 +2774,16 @@ function createTypesenseSearchAdapter(config) {
 			});
 			ensureOk(response, "Typesense search failed");
 			const rawPayload = await readResponseJson(response);
-			return ((filterBy ? rawPayload.results?.[0] ?? {} : rawPayload).hits ?? []).map((hit) => {
+			return ((filterBy ? rawPayload.results?.[0] ?? {} : rawPayload).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);
-				return {
-					id: typeof document.id === "string" ? document.id : String(document.url ?? content),
+				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),
@@ -1868,8 +2793,9 @@ function createTypesenseSearchAdapter(config) {
 						"text"
 					].includes(document.type) ? document.type : section ? "heading" : "page",
 					score: hit.text_match,
-					section
-				};
+					section,
+					...source ? { source } : {}
+				}];
 			});
 		}
 	};
@@ -1983,7 +2909,7 @@ function createMcpSearchAdapter(config) {
 					const echoedFilters = parseVerifiedMcpSearchFilters(parsed.filters);
 					if (!echoedFilters || !docsSearchFiltersMatch(query.filters ?? {}, echoedFilters)) return [];
 				}
-				return (Array.isArray(parsed) ? parsed : Array.isArray(parsed.results) ? parsed.results : Array.isArray(parsed.pages) ? parsed.pages : []).map(mapMcpSearchResult).filter((result) => Boolean(result));
+				return (Array.isArray(parsed) ? parsed : Array.isArray(parsed.results) ? parsed.results : Array.isArray(parsed.pages) ? parsed.pages : []).map((result) => mapMcpSearchResult(result, endpoint)).filter((result) => Boolean(result));
 			} finally {
 				if (sessionId) {
 					const cleanupController = new AbortController();
@@ -2006,9 +2932,62 @@ function createMcpSearchAdapter(config) {
 		}
 	};
 }
-function getAlgoliaBase(config) {
+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, "\\\"")}"`;
 }
@@ -2017,26 +2996,29 @@ function createAlgoliaSearchAdapter(config) {
 		name: "algolia",
 		async index(context) {
 			if (!config.adminApiKey) return;
-			ensureOk(await fetch(`${getAlgoliaBase(config)}/1/indexes/${encodeURIComponent(config.indexName)}/batch`, {
-				method: "POST",
-				headers: {
-					"Content-Type": "application/json",
-					"X-Algolia-Application-Id": config.appId,
-					"X-Algolia-API-Key": config.adminApiKey
-				},
-				body: JSON.stringify({ requests: context.documents.map((document) => ({
-					action: "addObject",
-					body: buildAlgoliaRecord(document)
-				})) }),
-				signal: context.signal
-			}), "Failed to sync documents to Algolia");
+			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) {
-			const scopedDocumentIds = resolveProviderScopeDocumentIds(query, context);
+			const corpusId = resolveHostedHumanCorpusId(config.syncNamespace, context);
+			const scopedDocumentIds = resolveProviderScopeDocumentIds(query, context, corpusId);
 			if (scopedDocumentIds?.length === 0) return [];
-			const filters = scopedDocumentIds?.map((id) => `objectID:${quoteAlgoliaFilterValue(id)}`).join(" OR ");
+			const scopedIdsFilter = scopedDocumentIds?.map((id) => `objectID:${quoteAlgoliaFilterValue(id)}`).join(" OR ");
+			const filterClauses = [corpusId ? `_tags:${quoteAlgoliaFilterValue(corpusId)}` : void 0, scopedIdsFilter ? corpusId ? `(${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) return [];
-			const response = await fetch(`${getAlgoliaBase(config)}/1/indexes/${encodeURIComponent(config.indexName)}/query`, {
+			const response = await fetch(`${getAlgoliaSearchBase(config)}/1/indexes/${encodeURIComponent(config.indexName)}/query`, {
 				method: "POST",
 				headers: {
 					"Content-Type": "application/json",
@@ -2046,17 +3028,26 @@ function createAlgoliaSearchAdapter(config) {
 				body: JSON.stringify({
 					query: query.query,
 					hitsPerPage: query.limit ?? config.maxResults ?? DEFAULT_SEARCH_LIMIT,
+					restrictSearchableAttributes: [
+						"title",
+						"section",
+						"content",
+						"description"
+					],
 					attributesToSnippet: ["content:20"],
 					...filters ? { filters } : {}
 				}),
 				signal: context.signal
 			});
 			ensureOk(response, "Algolia search failed");
-			return ((await readResponseJson(response)).hits ?? []).map((hit) => {
+			return ((await readResponseJson(response)).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;
-				return {
-					id: hit.objectID ?? String(hit.url ?? title),
+				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)),
@@ -2066,8 +3057,9 @@ function createAlgoliaSearchAdapter(config) {
 						"text"
 					].includes(hit.type) ? hit.type : section ? "heading" : "page",
 					score: hit._rankingInfo?.nbTypos != null ? 100 - hit._rankingInfo.nbTypos : void 0,
-					section
-				};
+					section,
+					...source ? { source } : {}
+				}];
 			});
 		}
 	};
@@ -2088,17 +3080,71 @@ function shouldSyncOnSearch(search) {
 }
 function getSyncKey(search, context) {
 	const raw = search.raw;
-	if (search.provider === "algolia" && raw?.provider === "algolia") return `algolia:${raw.appId}:${raw.indexName}:${context.locale ?? "__default__"}`;
-	if (search.provider === "typesense" && raw?.provider === "typesense") return `typesense:${raw.baseUrl}:${raw.collection}:${context.locale ?? "__default__"}`;
+	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);
-	if (syncedIndexes.has(syncKey)) return;
-	await adapter.index(context);
-	syncedIndexes.add(syncKey);
+	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);
+		}
+	}
 }
 async function performDocsSearch(options) {
 	const search = normalizeDocsSearchConfig(options.search);
@@ -2106,7 +3152,9 @@ async function performDocsSearch(options) {
 	const audience = resolveDocsSearchAudience(options.audience);
 	const filters = normalizeDocsSearchFilters(options.filters);
 	const hasFilters = hasDocsSearchFilters(filters);
-	const scopedPages = hasFilters ? options.pages.filter((page) => docsSearchPageMatchesFilters(resolveDocsSearchPageScope(page), filters)) : options.pages;
+	const corpusPages = options.pages.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);
@@ -2124,6 +3172,10 @@ async function performDocsSearch(options) {
 		locale: options.locale,
 		pathname: options.pathname,
 		siteTitle: options.siteTitle,
+		baseUrl: options.baseUrl,
+		indexBaseUrl,
+		chunking: search.chunking,
+		deferSourceProvenance: true,
 		signal: options.signal
 	};
 	const query = {
@@ -2134,17 +3186,47 @@ async function performDocsSearch(options) {
 		audience,
 		...hasFilters ? { filters } : {}
 	};
+	let currentIndexGeneration;
+	const getCurrentIndexGeneration = () => {
+		currentIndexGeneration ??= options.indexGeneration ? Promise.resolve(options.indexGeneration) : buildDocsSearchIndexGeneration(options.generationPages ?? options.pages, {
+			audience,
+			chunking: search.chunking,
+			locale: options.locale,
+			baseUrl: options.baseUrl
+		});
+		return currentIndexGeneration;
+	};
+	const requireCurrentIndexGeneration = search.provider === "algolia" || search.provider === "typesense";
+	const finalizeResults = async (results) => 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
+	});
 	try {
 		const adapter = await resolveSearchAdapter(search, context);
-		if (shouldSyncOnSearch(search) && typeof adapter.index === "function") await maybeSyncSearchIndex(adapter, search, audience === "agent" || hasFilters ? {
-			pages: options.pages,
-			documents: buildDocsSearchDocuments(options.pages, search.chunking, "human"),
-			audience: "human",
-			locale: options.locale,
-			pathname: options.pathname,
-			siteTitle: options.siteTitle,
-			signal: options.signal
-		} : 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,
+				chunking: search.chunking,
+				signal: options.signal
+			});
+		}
 		const adapterSearch = adapter.search(query, context);
 		let documents;
 		try {
@@ -2154,34 +3236,46 @@ async function performDocsSearch(options) {
 			throw error;
 		}
 		const results = await adapterSearch;
-		if (search.provider === "simple") return results;
+		if (search.provider === "simple") return finalizeResults(results);
 		const localAudienceProjectionResults = buildAudienceProjectionSearchResults(documents, options.query);
-		const localPagePaths = new Set(scopedPages.map((page) => normalizeUrlPathname(page.url)));
-		const allLocalPagePaths = hasFilters && search.provider === "mcp" ? new Set(options.pages.map((page) => normalizeUrlPathname(page.url))) : localPagePaths;
+		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 safeAdapterResults = sanitizeExternalAudienceSearchResults(results.filter((result) => !hasOppositeAudienceEvidence({
+		const isKnownLocalProviderResult = (result) => isLocalProviderResult(result, options.baseUrl) && localPagePaths.has(normalizeUrlRouteKey(result.url));
+		const expectedProviderGeneration = requireCurrentIndexGeneration ? audience === "human" ? await getCurrentIndexGeneration() : await buildDocsSearchIndexGeneration(options.generationPages ?? options.pages, {
+			audience: "human",
+			chunking: search.chunking,
+			locale: options.locale,
+			baseUrl: indexBaseUrl
+		}) : 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,
-			strictExternalOrigins: options.strictExternalOrigins
-		})), localAudienceProjectionResults, options.baseUrl, options.strictExternalOrigins, preserveUnmatched);
-		if (options.supplementExternalResults === false) return safeAdapterResults.slice(0, query.limit ?? search.maxResults ?? DEFAULT_SEARCH_LIMIT);
+			baseUrl: options.baseUrl
+		})), localAudienceProjectionResults, options.baseUrl, preserveUnmatched, requireCurrentIndexGeneration && audience === "agent");
+		if (options.supplementExternalResults === false) return finalizeResults(safeAdapterResults.slice(0, query.limit ?? search.maxResults ?? DEFAULT_SEARCH_LIMIT));
 		const simpleAudienceResults = audience === "agent" || results.length === 0 || safeAdapterResults.length < results.length ? await createSimpleSearchAdapter().search(query, context) : [];
 		const combinedResults = mergeSearchResults([
 			buildExactPageSearchResults(options.query, scopedPages, audience),
 			safeAdapterResults,
 			simpleAudienceResults
 		], audience === "agent" ? (result) => getAskAIResultKey(result, options.baseUrl, options.strictExternalOrigins) : void 0);
-		return prioritizeLiteralInsideResults(options.query, combinedResults).slice(0, query.limit ?? search.maxResults ?? DEFAULT_SEARCH_LIMIT);
+		return finalizeResults(prioritizeLiteralInsideResults(options.query, combinedResults).slice(0, query.limit ?? search.maxResults ?? DEFAULT_SEARCH_LIMIT));
 	} catch (error) {
 		if (options.failureMode === "throw") throw error;
-		return createSimpleSearchAdapter().search(query, context);
+		return finalizeResults(await createSimpleSearchAdapter().search(query, context));
 	}
 }
 function compareSearchMetadataValues(left, right) {
@@ -2197,11 +3291,11 @@ function boundedSearchWarningPageUrls(pages) {
 	return bounded.length > 0 ? bounded : void 0;
 }
 function findSearchResultPages(pages, results, baseUrl) {
-	const pagesByPath = new Map(pages.map((page) => [normalizeUrlPathname(page.url), page]));
+	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, true)) continue;
-		const page = pagesByPath.get(normalizeUrlPathname(result.url));
+		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));
@@ -2283,16 +3377,25 @@ function buildDocsSearchWarnings(options) {
 async function performDocsSearchWithMetadata(options) {
 	const audience = resolveDocsSearchAudience(options.audience);
 	const filters = normalizeDocsSearchFilters(options.filters);
-	const results = await performDocsSearch({
-		...options,
+	const search = normalizeDocsSearchConfig(options.search);
+	const indexGeneration = options.indexGeneration ?? await buildDocsSearchIndexGeneration(options.generationPages ?? options.pages, {
 		audience,
-		filters
+		chunking: search.chunking,
+		locale: options.locale,
+		baseUrl: options.baseUrl
 	});
+	const results = options.query.trim() ? await performDocsSearch({
+		...options,
+		audience,
+		filters,
+		indexGeneration
+	}) : [];
 	return {
 		format: "docs-search.v1",
 		query: options.query,
 		audience,
 		filters,
+		indexGeneration,
 		resultCount: results.length,
 		results,
 		warnings: buildDocsSearchWarnings({
@@ -2319,6 +3422,7 @@ async function buildDocsAskAIContext(options) {
 		pathname: options.pathname,
 		siteTitle: options.siteTitle,
 		baseUrl: options.baseUrl,
+		syncBaseUrl: options.syncBaseUrl,
 		limit: searchLimit,
 		filters: options.filters,
 		failureMode: options.searchFailureMode,
@@ -2330,7 +3434,7 @@ async function buildDocsAskAIContext(options) {
 	const rankedResults = searchResults.map((result, index) => {
 		const formatted = formatAskAIContextResult({
 			result,
-			page: findPageForSearchResult(options.pages, result, options.baseUrl, options.strictExternalOrigins),
+			page: findPageForSearchResult(options.pages, result, options.baseUrl),
 			maxChars: maxResultChars,
 			baseUrl: options.baseUrl
 		});
@@ -2383,4 +3487,4 @@ function createCustomSearchAdapter(adapter) {
 }
 
 //#endregion
-export { stripGeneratedAgentProvenance as A, inferDocsTelemetryAgentSurface as B, normalizeAgentVersion as C, normalizeGeneratedAgentContent as D, hashGeneratedAgentContent as E, emitDocsTelemetryAgentSurfaceEvent as F, normalizeDocsTelemetryOrigin as H, emitDocsTelemetryEvent as I, emitDocsTelemetryMcpToolEvent as L, resolvePageSidebarFolderIndexBehavior as M, resolveSidebarFolderIndexBehavior as N, parseGeneratedAgentDocument as O, resolveSidebarFolderIndexBehaviorForPath as P, emitDocsTelemetryProjectEvent as R, normalizeAgentScopeValues as S, GENERATED_AGENT_PROVENANCE_VERSION as T, resolveDocsTelemetryConfig as U, isLocalDocsTelemetryOrigin as V, resolveSearchRequestConfig as _, createMcpSearchAdapter as a, normalizeAgentFramework as b, formatDocsAskAIPackageHints as c, performDocsSearch as d, performDocsSearchWithMetadata as f, resolveDocsSearchRequest as g, resolveDocsSearchFilters as h, createCustomSearchAdapter as i, applySidebarFolderIndexBehavior as j, serializeGeneratedAgentDocument as k, inferDocsAskAIPackageHints as l, resolveDocsSearchAudience as m, buildDocsSearchDocuments as n, createSimpleSearchAdapter as o, resolveAskAISearchRequestConfig as p, createAlgoliaSearchAdapter as r, createTypesenseSearchAdapter as s, buildDocsAskAIContext as t, normalizeDocsSearchFilters as u, agentVersionConstraintMatches as v, GENERATED_AGENT_PROVENANCE_MARKER as w, normalizeAgentLocale as x, agentVersionConstraintsOverlap as y, getDocsTelemetryFeatures as z };
+export { GENERATED_AGENT_PROVENANCE_MARKER as A, resolveSidebarFolderIndexBehaviorForPath as B, agentVersionConstraintsOverlap as C, normalizeAgentVersion as D, normalizeAgentScopeValues as E, serializeGeneratedAgentDocument as F, getDocsTelemetryFeatures as G, emitDocsTelemetryEvent as H, stripGeneratedAgentProvenance as I, normalizeDocsTelemetryOrigin as J, inferDocsTelemetryAgentSurface as K, applySidebarFolderIndexBehavior as L, hashGeneratedAgentContent as M, normalizeGeneratedAgentContent as N, digestDocsRetrievalContent as O, parseGeneratedAgentDocument as P, resolvePageSidebarFolderIndexBehavior as R, agentVersionConstraintMatches as S, normalizeAgentLocale as T, emitDocsTelemetryMcpToolEvent as U, emitDocsTelemetryAgentSurfaceEvent as V, emitDocsTelemetryProjectEvent as W, resolveDocsTelemetryConfig as Y, resolveDocsSearchAudience as _, createCustomSearchAdapter as a, resolveSearchRequestConfig as b, createTypesenseSearchAdapter as c, inferDocsAskAIPackageHints as d, normalizeDocsSearchFilters as f, resolveDocsRetrievalLastModified as g, resolveAskAISearchRequestConfig as h, createAlgoliaSearchAdapter as i, GENERATED_AGENT_PROVENANCE_VERSION as j, isDocsRetrievalCanonicalUrl as k, enrichDocsSearchDocumentsWithProvenance as l, performDocsSearchWithMetadata as m, buildDocsRetrievalDigestProjection as n, createMcpSearchAdapter as o, performDocsSearch as p, isLocalDocsTelemetryOrigin as q, buildDocsSearchDocuments as r, createSimpleSearchAdapter as s, buildDocsAskAIContext as t, formatDocsAskAIPackageHints as u, resolveDocsSearchFilters as v, normalizeAgentFramework as w, agentVersionConstraintGroupsOverlap as x, resolveDocsSearchRequest as y, resolveSidebarFolderIndexBehavior as z };