@farming-labs/docs 0.2.62 → 0.2.63

package/dist/agent-evals-B7MIxuEX.mjs

@@ -0,0 +1,2144 @@
+import { m as findDocsMarkdownSection, p as resolveSearchRequestConfig, t as buildDocsAskAIContext, u as performDocsSearch } from "./search-B6V6qtiI.mjs";
+import { a as normalizeAgentScopeValues, i as normalizeAgentLocale, n as agentVersionConstraintsOverlap, o as normalizeAgentVersion, r as normalizeAgentFramework, t as agentVersionConstraintMatches } from "./agent-scope-C_U--OZ7.mjs";
+import { buildDocsMcpContext } from "./mcp.mjs";
+import { i as validateCodeBlockPlans, n as planCodeBlockTargets, r as resolveDocsCodeBlocksValidateConfig, t as extractCodeBlocksFromMarkdown } from "./code-blocks-DnNVNK2M.mjs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import { createJiti } from "jiti";
+
+//#region src/review.ts
+const DEFAULT_DOCS_REVIEW_WORKFLOW_PATH = ".github/workflows/docs-review.yml";
+const DEFAULT_DOCS_REVIEW_REUSABLE_WORKFLOW_PATH = ".github/workflows/docs-review-reusable.yml";
+const DEFAULT_DOCS_REVIEW_REUSABLE_WORKFLOW = "farming-labs/docs/.github/workflows/docs-review-reusable.yml@main";
+const LOCAL_DOCS_REVIEW_REUSABLE_WORKFLOW = "./.github/workflows/docs-review-reusable.yml";
+const DEFAULT_DOCS_REVIEW_PNPM_VERSION = "10";
+const DEFAULT_DOCS_REVIEW_SCORE_THRESHOLD = 80;
+const DEFAULT_DOCS_REVIEW_CI_NAME = "docs-review";
+const DEFAULT_REVIEW_RULES = {
+	brokenLinks: "error",
+	frontmatter: "error",
+	duplicateSlugs: "error",
+	invalidMdx: "error",
+	configExamples: "warn",
+	codeFenceMetadata: "warn",
+	runnableMetadata: "warn",
+	agentContext: "warn",
+	commandHealth: "warn",
+	relatedCoverage: "suggestion",
+	configConfidence: "warn",
+	agentSurfaceDrift: "error",
+	goldenTasks: "warn"
+};
+const DEFAULT_REVIEW_WEIGHTS = {
+	error: 20,
+	warn: 8,
+	suggestion: 2
+};
+const REVIEW_SEVERITIES = new Set([
+	"off",
+	"suggestion",
+	"warn",
+	"error"
+]);
+const REVIEW_CI_MODES = new Set([
+	"off",
+	"warn",
+	"block"
+]);
+const FILE_EXTS = [
+	"tsx",
+	"ts",
+	"jsx",
+	"js"
+];
+function resolveDocsReviewConfig(review) {
+	if (review === false) return {
+		enabled: false,
+		ci: {
+			enabled: false,
+			name: DEFAULT_DOCS_REVIEW_CI_NAME,
+			mode: "off",
+			annotations: false,
+			comment: false
+		},
+		score: {
+			threshold: DEFAULT_DOCS_REVIEW_SCORE_THRESHOLD,
+			weights: DEFAULT_REVIEW_WEIGHTS
+		},
+		rules: DEFAULT_REVIEW_RULES
+	};
+	const objectConfig = review && typeof review === "object" ? review : {};
+	const ciConfig = objectConfig.ci;
+	const ciObject = ciConfig && typeof ciConfig === "object" ? ciConfig : {};
+	const configuredMode = ciObject.mode;
+	const mode = configuredMode && REVIEW_CI_MODES.has(configuredMode) ? configuredMode : "warn";
+	const enabled = objectConfig.enabled !== false;
+	const ciEnabled = enabled && ciConfig !== false && ciObject.enabled !== false && mode !== "off";
+	return {
+		enabled,
+		ci: {
+			enabled: ciEnabled,
+			name: normalizeCiName(ciObject.name),
+			mode: ciEnabled ? mode : "off",
+			annotations: ciObject.annotations !== false,
+			comment: ciObject.comment !== false
+		},
+		score: {
+			threshold: clampScoreThreshold(objectConfig.score?.threshold),
+			weights: {
+				error: normalizeWeight(objectConfig.score?.weights?.error, DEFAULT_REVIEW_WEIGHTS.error),
+				warn: normalizeWeight(objectConfig.score?.weights?.warn, DEFAULT_REVIEW_WEIGHTS.warn),
+				suggestion: normalizeWeight(objectConfig.score?.weights?.suggestion, DEFAULT_REVIEW_WEIGHTS.suggestion)
+			}
+		},
+		rules: {
+			...DEFAULT_REVIEW_RULES,
+			...normalizeRules(objectConfig.rules)
+		}
+	};
+}
+function buildDocsReviewWorkflow(options = {}) {
+	const packageManager = options.packageManager ?? "npm";
+	const ciName = normalizeCiName(options.ciName);
+	const projectDir = normalizeProjectDir(options.projectDir);
+	const configPath = options.configPath ?? "docs.config.ts";
+	const reusableWorkflow = options.reusableWorkflow ?? DEFAULT_DOCS_REVIEW_REUSABLE_WORKFLOW;
+	const filters = normalizePathFilters(options.pathFilters);
+	const workflowInputs = [
+		["check-name", ciName],
+		["config", configPath],
+		["working-directory", projectDir],
+		["package-manager", packageManager],
+		options.pnpmVersion ? ["pnpm-version", options.pnpmVersion] : void 0,
+		options.buildCommand ? ["build-command", options.buildCommand] : void 0,
+		options.reviewCommand ? ["review-command", options.reviewCommand] : void 0
+	].filter((input) => Boolean(input)).map(([key, value]) => `      ${key}: ${JSON.stringify(value)}`).join("\n");
+	return `# Generated by @farming-labs/docs. You can edit this file.
+name: Docs Review
+
+on:
+  pull_request:
+    paths:
+${filters.map((filter) => `      - ${JSON.stringify(filter)}`).join("\n")}
+
+permissions:
+  contents: read
+  checks: write
+  pull-requests: write
+
+jobs:
+  docs-review:
+    name: ${JSON.stringify(ciName)}
+    uses: ${reusableWorkflow}
+    with:
+${workflowInputs}
+    permissions:
+      contents: read
+      checks: write
+      pull-requests: write
+`;
+}
+function ensureDocsReviewWorkflow(options) {
+	const rootDir = options.rootDir;
+	const repoRoot = findGitRoot(rootDir) ?? rootDir;
+	const workflowRelativePath = options.workflowPath ?? DEFAULT_DOCS_REVIEW_WORKFLOW_PATH;
+	const workflowPath = isAbsolute(workflowRelativePath) ? workflowRelativePath : join(repoRoot, workflowRelativePath);
+	const resultRelativePath = toPosixPath(relative(repoRoot, workflowPath));
+	const review = resolveDocsReviewConfig(options.config?.review ?? readDocsReviewConfigFromSource(options.configContent ?? readConfig(rootDir)));
+	if (!review.enabled || !review.ci.enabled) return {
+		status: "disabled",
+		path: workflowPath,
+		relativePath: resultRelativePath
+	};
+	if (existsSync(workflowPath)) return {
+		status: "exists",
+		path: workflowPath,
+		relativePath: resultRelativePath
+	};
+	const configPath = options.configPath ?? findDocsConfigPath(rootDir);
+	const configContent = options.configContent ?? readConfig(rootDir, configPath);
+	const projectDir = toPosixPath(relative(repoRoot, rootDir)) || ".";
+	const packageManager = detectPackageManager(repoRoot);
+	const workflow = buildDocsReviewWorkflow({
+		packageManager,
+		ciName: review.ci.name,
+		reusableWorkflow: hasLocalDocsWorkspacePackage(repoRoot) ? LOCAL_DOCS_REVIEW_REUSABLE_WORKFLOW : DEFAULT_DOCS_REVIEW_REUSABLE_WORKFLOW,
+		pnpmVersion: detectPnpmVersionFallback(repoRoot, packageManager),
+		projectDir,
+		configPath,
+		buildCommand: detectLocalDocsCliBuildCommand(repoRoot, packageManager),
+		reviewCommand: detectLocalDocsCliReviewCommand(repoRoot, rootDir),
+		pathFilters: buildDocsReviewWorkflowPathFilters({
+			rootDir,
+			repoRoot,
+			config: options.config,
+			configPath,
+			configContent
+		})
+	});
+	mkdirSync(dirname(workflowPath), { recursive: true });
+	writeFileSync(workflowPath, workflow, "utf-8");
+	options.log?.(`[docs] Created ${resultRelativePath} for Docs Review CI.`);
+	return {
+		status: "created",
+		path: workflowPath,
+		relativePath: resultRelativePath
+	};
+}
+function readDocsReviewConfigFromSource(content) {
+	if (!content) return void 0;
+	const rootObject = extractRootObjectLiteral(content) ?? content;
+	const reviewCursor = findTopLevelPropertyValueIndex(rootObject, "review");
+	if (reviewCursor === void 0) return void 0;
+	if (rootObject.startsWith("true", reviewCursor)) return true;
+	if (rootObject.startsWith("false", reviewCursor)) return false;
+	if (rootObject[reviewCursor] !== "{") return void 0;
+	const reviewEnd = findMatchingObjectEnd(rootObject, reviewCursor);
+	if (reviewEnd === void 0) return void 0;
+	const reviewBlock = rootObject.slice(reviewCursor + 1, reviewEnd);
+	const scoreBlock = extractTopLevelObjectLiteral(reviewBlock, "score");
+	const ciCursor = findTopLevelPropertyValueIndex(reviewBlock, "ci");
+	const rulesBlock = extractTopLevelObjectLiteral(reviewBlock, "rules");
+	const ci = ciCursor === void 0 ? void 0 : reviewBlock.startsWith("true", ciCursor) ? true : reviewBlock.startsWith("false", ciCursor) ? false : reviewBlock[ciCursor] === "{" ? readReviewCiObject(reviewBlock, ciCursor) : void 0;
+	return {
+		enabled: readTopLevelBoolean(reviewBlock, "enabled"),
+		score: scoreBlock ? {
+			threshold: readTopLevelNumber(scoreBlock, "threshold"),
+			weights: readReviewWeights(scoreBlock)
+		} : void 0,
+		ci,
+		rules: rulesBlock ? readReviewRules(rulesBlock) : void 0
+	};
+}
+function buildDocsReviewWorkflowPathFilters(options) {
+	const repoRoot = options.repoRoot ?? findGitRoot(options.rootDir) ?? options.rootDir;
+	const configPath = options.configPath ?? findDocsConfigPath(options.rootDir);
+	const configContent = options.configContent ?? readConfig(options.rootDir, configPath);
+	const entry = options.config?.entry ?? readTopLevelString(configContent, "entry") ?? "docs";
+	const contentDir = options.config?.contentDir ?? readTopLevelString(configContent, "contentDir");
+	const projectDir = toPosixPath(relative(repoRoot, options.rootDir));
+	const projectPrefix = projectDir && projectDir !== "." ? `${projectDir}/` : "";
+	const candidates = [
+		prefixPath(projectPrefix, configPath),
+		prefixPath(projectPrefix, `${entry}/**`),
+		prefixPath(projectPrefix, `app/${entry}/**`),
+		prefixPath(projectPrefix, `src/app/${entry}/**`),
+		contentDir ? prefixPath(projectPrefix, `${trimSlashes(contentDir)}/**`) : void 0,
+		prefixPath(projectPrefix, "content/docs/**"),
+		prefixPath(projectPrefix, "src/content/docs/**"),
+		prefixPath(projectPrefix, "src/lib/docs.config.*"),
+		DEFAULT_DOCS_REVIEW_WORKFLOW_PATH,
+		DEFAULT_DOCS_REVIEW_REUSABLE_WORKFLOW_PATH
+	];
+	return Array.from(new Set(candidates.filter((candidate) => Boolean(candidate))));
+}
+function normalizeRules(rules) {
+	if (!rules) return {};
+	const knownRules = new Set(Object.keys(DEFAULT_REVIEW_RULES));
+	return Object.fromEntries(Object.entries(rules).filter((entry) => knownRules.has(entry[0]) && REVIEW_SEVERITIES.has(entry[1])));
+}
+function normalizeWeight(value, fallback) {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+function normalizeCiName(value) {
+	return value?.trim() || DEFAULT_DOCS_REVIEW_CI_NAME;
+}
+function clampScoreThreshold(value) {
+	if (typeof value !== "number" || !Number.isFinite(value)) return DEFAULT_DOCS_REVIEW_SCORE_THRESHOLD;
+	return Math.min(100, Math.max(0, Math.round(value)));
+}
+function readReviewCiObject(source, cursor) {
+	const end = findMatchingObjectEnd(source, cursor);
+	if (end === void 0) return void 0;
+	const block = source.slice(cursor + 1, end);
+	const mode = readTopLevelString(block, "mode");
+	return {
+		enabled: readTopLevelBoolean(block, "enabled"),
+		name: readTopLevelString(block, "name"),
+		mode: mode && REVIEW_CI_MODES.has(mode) ? mode : void 0,
+		annotations: readTopLevelBoolean(block, "annotations"),
+		comment: readTopLevelBoolean(block, "comment")
+	};
+}
+function readReviewRules(block) {
+	const rules = {};
+	for (const key of Object.keys(DEFAULT_REVIEW_RULES)) {
+		const value = readTopLevelString(block, key);
+		if (value && REVIEW_SEVERITIES.has(value)) rules[key] = value;
+	}
+	return rules;
+}
+function readReviewWeights(block) {
+	const weightsBlock = extractTopLevelObjectLiteral(block, "weights");
+	if (!weightsBlock) return void 0;
+	return {
+		error: readTopLevelNumber(weightsBlock, "error"),
+		warn: readTopLevelNumber(weightsBlock, "warn"),
+		suggestion: readTopLevelNumber(weightsBlock, "suggestion")
+	};
+}
+function detectPackageManager(rootDir) {
+	if (existsSync(join(rootDir, "pnpm-lock.yaml"))) return "pnpm";
+	if (existsSync(join(rootDir, "yarn.lock"))) return "yarn";
+	if (existsSync(join(rootDir, "bun.lock")) || existsSync(join(rootDir, "bun.lockb"))) return "bun";
+	return "npm";
+}
+function detectLocalDocsCliBuildCommand(repoRoot, packageManager) {
+	if (!hasLocalDocsWorkspacePackage(repoRoot)) return void 0;
+	if (packageManager === "pnpm") return "pnpm --filter @farming-labs/docs run build";
+	if (packageManager === "yarn") return "yarn workspace @farming-labs/docs build";
+	if (packageManager === "bun") return "bun run --filter @farming-labs/docs build";
+	return "npm run build --workspace=@farming-labs/docs";
+}
+function detectPnpmVersionFallback(repoRoot, packageManager) {
+	if (packageManager !== "pnpm") return void 0;
+	try {
+		if (JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf-8")).packageManager?.startsWith("pnpm@")) return void 0;
+	} catch {}
+	return DEFAULT_DOCS_REVIEW_PNPM_VERSION;
+}
+function detectLocalDocsCliReviewCommand(repoRoot, rootDir) {
+	if (!hasLocalDocsWorkspacePackage(repoRoot)) return void 0;
+	return `node ${shellQuote(toPosixPath(relative(rootDir, join(repoRoot, "packages", "docs", "dist", "cli", "index.mjs"))) || "./packages/docs/dist/cli/index.mjs")}`;
+}
+function hasLocalDocsWorkspacePackage(repoRoot) {
+	const packageJsonPath = join(repoRoot, "packages", "docs", "package.json");
+	if (!existsSync(packageJsonPath)) return false;
+	try {
+		const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+		return packageJson.name === "@farming-labs/docs" && Boolean(packageJson.scripts?.build);
+	} catch {
+		return false;
+	}
+}
+function shellQuote(value) {
+	if (/^[A-Za-z0-9_./:-]+$/.test(value)) return value;
+	return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function normalizeProjectDir(value) {
+	if (!value || value === "") return ".";
+	return toPosixPath(value).replace(/\/+$/, "") || ".";
+}
+function normalizePathFilters(filters) {
+	const normalized = (filters && filters.length > 0 ? filters : ["docs.config.*", "app/docs/**"]).map((filter) => toPosixPath(filter).replace(/^\.\/+/, "")).filter(Boolean);
+	return Array.from(new Set(normalized));
+}
+function findGitRoot(start) {
+	let current = start;
+	while (true) {
+		if (existsSync(join(current, ".git"))) return current;
+		const parent = dirname(current);
+		if (parent === current) return void 0;
+		current = parent;
+	}
+}
+function findDocsConfigPath(rootDir) {
+	for (const ext of FILE_EXTS) {
+		const path = `docs.config.${ext}`;
+		if (existsSync(join(rootDir, path))) return path;
+	}
+	return "docs.config.ts";
+}
+function readConfig(rootDir, configPath = findDocsConfigPath(rootDir)) {
+	const fullPath = join(rootDir, configPath);
+	if (!existsSync(fullPath)) return void 0;
+	try {
+		return readFileSync(fullPath, "utf-8");
+	} catch {
+		return;
+	}
+}
+function prefixPath(prefix, value) {
+	return `${prefix}${toPosixPath(value).replace(/^\.\/+/, "")}`;
+}
+function trimSlashes(value) {
+	return toPosixPath(value).replace(/^\/+|\/+$/g, "");
+}
+function toPosixPath(value) {
+	return value.replaceAll("\\", "/");
+}
+function extractRootObjectLiteral(content) {
+	const candidateIndexes = [content.search(/\bdefineDocs\s*\(/), content.search(/\bexport\s+default\b/)].filter((value) => value !== -1);
+	for (const startIndex of candidateIndexes) {
+		const braceStart = content.indexOf("{", startIndex);
+		if (braceStart === -1) continue;
+		const braceEnd = findMatchingObjectEnd(content, braceStart);
+		if (braceEnd !== void 0) return content.slice(braceStart + 1, braceEnd);
+	}
+}
+function extractTopLevelObjectLiteral(content, key) {
+	const cursor = findTopLevelPropertyValueIndex(content, key);
+	if (cursor === void 0 || content[cursor] !== "{") return void 0;
+	const end = findMatchingObjectEnd(content, cursor);
+	return end === void 0 ? void 0 : content.slice(cursor + 1, end);
+}
+function readTopLevelBoolean(content, key) {
+	const cursor = findTopLevelPropertyValueIndex(content, key);
+	if (cursor === void 0) return void 0;
+	if (content.startsWith("true", cursor)) return true;
+	if (content.startsWith("false", cursor)) return false;
+}
+function readTopLevelNumber(content, key) {
+	const cursor = findTopLevelPropertyValueIndex(content, key);
+	if (cursor === void 0) return void 0;
+	const match = content.slice(cursor).match(/^-?\d+(?:\.\d+)?/);
+	if (!match) return void 0;
+	const value = Number(match[0]);
+	return Number.isFinite(value) ? value : void 0;
+}
+function readTopLevelString(content, key) {
+	if (!content) return void 0;
+	const cursor = findTopLevelPropertyValueIndex(content, key);
+	if (cursor === void 0) return void 0;
+	const quote = content[cursor];
+	if (quote !== "\"" && quote !== "'") return void 0;
+	let value = "";
+	for (let index = cursor + 1; index < content.length; index += 1) {
+		const char = content[index];
+		if (char === "\\") {
+			const escaped = content[index + 1];
+			if (escaped) {
+				value += escaped;
+				index += 1;
+			}
+			continue;
+		}
+		if (char === quote) return value;
+		value += char;
+	}
+}
+function findTopLevelPropertyValueIndex(block, key) {
+	let objectDepth = 0;
+	let arrayDepth = 0;
+	let parenDepth = 0;
+	let inString = null;
+	let inLineComment = false;
+	let inBlockComment = false;
+	let escaped = false;
+	for (let index = 0; index < block.length; index += 1) {
+		const char = block[index];
+		const next = block[index + 1];
+		if (inLineComment) {
+			if (char === "\n") inLineComment = false;
+			continue;
+		}
+		if (inBlockComment) {
+			if (char === "*" && next === "/") {
+				inBlockComment = false;
+				index += 1;
+			}
+			continue;
+		}
+		if (inString) {
+			if (escaped) {
+				escaped = false;
+				continue;
+			}
+			if (char === "\\") {
+				escaped = true;
+				continue;
+			}
+			if (char === inString) inString = null;
+			continue;
+		}
+		if (char === "/" && next === "/") {
+			inLineComment = true;
+			index += 1;
+			continue;
+		}
+		if (char === "/" && next === "*") {
+			inBlockComment = true;
+			index += 1;
+			continue;
+		}
+		if (char === "\"" || char === "'" || char === "`") {
+			inString = char;
+			continue;
+		}
+		if (char === "{") {
+			objectDepth += 1;
+			continue;
+		}
+		if (char === "}") {
+			objectDepth = Math.max(0, objectDepth - 1);
+			continue;
+		}
+		if (char === "[") {
+			arrayDepth += 1;
+			continue;
+		}
+		if (char === "]") {
+			arrayDepth = Math.max(0, arrayDepth - 1);
+			continue;
+		}
+		if (char === "(") {
+			parenDepth += 1;
+			continue;
+		}
+		if (char === ")") {
+			parenDepth = Math.max(0, parenDepth - 1);
+			continue;
+		}
+		if (objectDepth !== 0 || arrayDepth !== 0 || parenDepth !== 0) continue;
+		if (!block.startsWith(key, index)) continue;
+		const before = block[index - 1] ?? "";
+		const after = block[index + key.length] ?? "";
+		if (/[A-Za-z0-9_$]/.test(before) || /[A-Za-z0-9_$]/.test(after)) continue;
+		let cursor = index + key.length;
+		while (/\s/.test(block[cursor] ?? "")) cursor += 1;
+		if (block[cursor] !== ":") continue;
+		cursor += 1;
+		while (/\s/.test(block[cursor] ?? "")) cursor += 1;
+		return cursor;
+	}
+}
+function findMatchingObjectEnd(block, start) {
+	let depth = 0;
+	let inString = null;
+	let inLineComment = false;
+	let inBlockComment = false;
+	let escaped = false;
+	for (let index = start; index < block.length; index += 1) {
+		const char = block[index];
+		const next = block[index + 1];
+		if (inLineComment) {
+			if (char === "\n") inLineComment = false;
+			continue;
+		}
+		if (inBlockComment) {
+			if (char === "*" && next === "/") {
+				inBlockComment = false;
+				index += 1;
+			}
+			continue;
+		}
+		if (inString) {
+			if (escaped) {
+				escaped = false;
+				continue;
+			}
+			if (char === "\\") {
+				escaped = true;
+				continue;
+			}
+			if (char === inString) inString = null;
+			continue;
+		}
+		if (char === "/" && next === "/") {
+			inLineComment = true;
+			index += 1;
+			continue;
+		}
+		if (char === "/" && next === "*") {
+			inBlockComment = true;
+			index += 1;
+			continue;
+		}
+		if (char === "\"" || char === "'" || char === "`") {
+			inString = char;
+			continue;
+		}
+		if (char === "{") {
+			depth += 1;
+			continue;
+		}
+		if (char !== "}") continue;
+		depth -= 1;
+		if (depth === 0) return index;
+	}
+}
+
+//#endregion
+//#region src/agent-evals.ts
+const DEFAULT_TOP_K = 5;
+const DEFAULT_TOKEN_BUDGET = 4e3;
+const CONTEXT_SEPARATOR = "\n\n---\n\n";
+const STATIC_CODE_PLAN_CONFIG = resolveDocsCodeBlocksValidateConfig(true);
+const STATIC_JITI = createJiti(import.meta.url, {
+	fsCache: false,
+	moduleCache: false
+});
+const EXECUTABLE_LANGUAGES = new Set([
+	"bash",
+	"curl",
+	"javascript",
+	"js",
+	"jsx",
+	"json",
+	"node",
+	"py",
+	"python",
+	"rb",
+	"ruby",
+	"sh",
+	"shell",
+	"ts",
+	"tsx",
+	"typescript",
+	"zsh"
+]);
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeRuntimeString(value, path, issues, required = false) {
+	if (value === void 0) {
+		if (required) issues.push(`${path} must be a non-empty string.`);
+		return;
+	}
+	if (typeof value !== "string" || !value.trim()) {
+		issues.push(`${path} must be a non-empty string.`);
+		return;
+	}
+	return value.trim();
+}
+function normalizeRuntimeStringList(value, path, issues, options = {}) {
+	if (value === void 0) {
+		if (options.required) issues.push(`${path} must be a non-empty string array.`);
+		return;
+	}
+	if (!Array.isArray(value)) {
+		issues.push(`${path} must be a string array.`);
+		return [];
+	}
+	const normalized = [];
+	let hasInvalidItem = false;
+	for (const item of value) {
+		if (typeof item !== "string" || !item.trim()) {
+			hasInvalidItem = true;
+			continue;
+		}
+		if (!normalized.includes(item.trim())) normalized.push(item.trim());
+	}
+	if (hasInvalidItem) issues.push(`${path} must contain only non-empty strings.`);
+	if (options.required && normalized.length === 0) issues.push(`${path} must contain at least one source.`);
+	return normalized;
+}
+function normalizeRuntimeNumber(value, path, issues, options = {}) {
+	if (value === void 0) return void 0;
+	if (typeof value !== "number" || !Number.isFinite(value) || options.integer && !Number.isInteger(value) || options.minimum !== void 0 && value < options.minimum || options.maximum !== void 0 && value > options.maximum) {
+		const range = options.minimum !== void 0 || options.maximum !== void 0 ? ` between ${options.minimum ?? "-Infinity"} and ${options.maximum ?? "Infinity"}` : "";
+		issues.push(`${path} must be a finite${options.integer ? " integer" : " number"}${range}.`);
+		return;
+	}
+	return value;
+}
+function normalizeRuntimeFilters(value, path, issues) {
+	if (value === void 0) return void 0;
+	if (!isRecord(value)) {
+		issues.push(`${path} must be an object.`);
+		return;
+	}
+	const framework = normalizeRuntimeString(value.framework, `${path}.framework`, issues);
+	const version = normalizeRuntimeString(value.version, `${path}.version`, issues);
+	const locale = normalizeRuntimeString(value.locale, `${path}.locale`, issues);
+	return framework || version || locale ? {
+		framework,
+		version,
+		locale
+	} : void 0;
+}
+function normalizeRuntimeEnum(value, path, issues, allowed) {
+	if (value === void 0) return void 0;
+	if (typeof value !== "string" || !allowed.includes(value)) {
+		issues.push(`${path} must be one of ${allowed.map((item) => JSON.stringify(item)).join(", ")}.`);
+		return;
+	}
+	return value;
+}
+function normalizeRuntimeAnswerExpectation(value, path, issues) {
+	if (value === void 0) return void 0;
+	if (!isRecord(value)) {
+		issues.push(`${path} must be an object.`);
+		return;
+	}
+	return {
+		includes: normalizeRuntimeStringList(value.includes, `${path}.includes`, issues),
+		excludes: normalizeRuntimeStringList(value.excludes, `${path}.excludes`, issues),
+		requiredCitations: normalizeRuntimeStringList(value.requiredCitations, `${path}.requiredCitations`, issues),
+		allowedCitations: normalizeRuntimeStringList(value.allowedCitations, `${path}.allowedCitations`, issues),
+		forbiddenCitations: normalizeRuntimeStringList(value.forbiddenCitations, `${path}.forbiddenCitations`, issues)
+	};
+}
+function normalizeRuntimeExamples(value, path, issues) {
+	if (value === void 0) return void 0;
+	if (!Array.isArray(value)) {
+		issues.push(`${path} must be an array.`);
+		return [];
+	}
+	return value.flatMap((item, index) => {
+		const itemPath = `${path}[${index}]`;
+		if (!isRecord(item)) {
+			issues.push(`${itemPath} must be an object.`);
+			return [];
+		}
+		const source = normalizeRuntimeString(item.source, `${itemPath}.source`, issues);
+		const language = normalizeRuntimeString(item.language, `${itemPath}.language`, issues);
+		const framework = normalizeRuntimeString(item.framework, `${itemPath}.framework`, issues);
+		const packageManager = normalizeRuntimeString(item.packageManager, `${itemPath}.packageManager`, issues);
+		const title = normalizeRuntimeString(item.title, `${itemPath}.title`, issues);
+		const includes = normalizeRuntimeStringList(item.includes, `${itemPath}.includes`, issues);
+		let runnable;
+		if (item.runnable !== void 0) if (typeof item.runnable === "boolean") runnable = item.runnable;
+		else issues.push(`${itemPath}.runnable must be a boolean.`);
+		const verification = normalizeRuntimeEnum(item.verification, `${itemPath}.verification`, issues, [
+			"present",
+			"syntax",
+			"execute"
+		]);
+		return [{
+			source,
+			language,
+			framework,
+			packageManager,
+			title,
+			runnable,
+			includes,
+			verification
+		}];
+	});
+}
+function normalizeGoldenTaskInput(value, index, initialIssues = []) {
+	const issues = [...initialIssues];
+	const path = `tasks[${index}]`;
+	const input = isRecord(value) ? value : {};
+	if (!isRecord(value)) issues.push(`${path} must be an object.`);
+	const id = normalizeRuntimeString(input.id, `${path}.id`, issues, true) ?? `invalid-task-${index + 1}`;
+	const query = normalizeRuntimeString(input.query, `${path}.query`, issues, true) ?? "";
+	const filters = normalizeRuntimeFilters(input.filters, `${path}.filters`, issues);
+	const tokenBudget = normalizeRuntimeNumber(input.tokenBudget, `${path}.tokenBudget`, issues, {
+		minimum: 1,
+		integer: true
+	});
+	const topK = normalizeRuntimeNumber(input.topK, `${path}.topK`, issues, {
+		minimum: 1,
+		integer: true
+	});
+	const surface = normalizeRuntimeEnum(input.surface, `${path}.surface`, issues, [
+		"mcp-context",
+		"configured-search",
+		"ask-ai-context"
+	]);
+	const expectPath = `${path}.expect`;
+	const expectation = isRecord(input.expect) ? input.expect : {};
+	if (!isRecord(input.expect)) issues.push(`${expectPath} must be an object.`);
+	const relevantSources = normalizeRuntimeStringList(expectation.relevantSources, `${expectPath}.relevantSources`, issues, { required: true }) ?? [];
+	const allowedSources = normalizeRuntimeStringList(expectation.allowedSources, `${expectPath}.allowedSources`, issues);
+	const forbiddenSources = normalizeRuntimeStringList(expectation.forbiddenSources, `${expectPath}.forbiddenSources`, issues);
+	const requiredCitations = normalizeRuntimeStringList(expectation.requiredCitations, `${expectPath}.requiredCitations`, issues);
+	const minRecallAtK = normalizeRuntimeNumber(expectation.minRecallAtK, `${expectPath}.minRecallAtK`, issues, {
+		minimum: 0,
+		maximum: 1
+	});
+	const maxFirstRelevantRank = normalizeRuntimeNumber(expectation.maxFirstRelevantRank, `${expectPath}.maxFirstRelevantRank`, issues, {
+		minimum: 1,
+		integer: true
+	});
+	const minUsefulByteRatio = normalizeRuntimeNumber(expectation.minUsefulByteRatio, `${expectPath}.minUsefulByteRatio`, issues, {
+		minimum: 0,
+		maximum: 1
+	});
+	const examples = normalizeRuntimeExamples(expectation.examples, `${expectPath}.examples`, issues);
+	const scope = normalizeRuntimeFilters(expectation.scope, `${expectPath}.scope`, issues);
+	const answer = normalizeRuntimeAnswerExpectation(expectation.answer, `${expectPath}.answer`, issues);
+	const forbidden = forbiddenSources ?? [];
+	for (const [name, sources] of [
+		["relevantSources", relevantSources],
+		["allowedSources", allowedSources ?? []],
+		["requiredCitations", requiredCitations ?? []]
+	]) {
+		const overlaps = sources.filter((source) => forbidden.some((forbiddenSource) => sourceMatches(source, forbiddenSource) || sourceMatches(forbiddenSource, source)));
+		if (overlaps.length > 0) issues.push(`${expectPath}.${name} must not overlap ${expectPath}.forbiddenSources (${overlaps.join(", ")}).`);
+	}
+	return {
+		task: {
+			id,
+			query,
+			filters,
+			tokenBudget,
+			topK,
+			surface,
+			expect: {
+				relevantSources,
+				allowedSources,
+				forbiddenSources,
+				requiredCitations,
+				minRecallAtK,
+				maxFirstRelevantRank,
+				minUsefulByteRatio,
+				examples,
+				scope,
+				answer
+			}
+		},
+		issues
+	};
+}
+function round(value) {
+	return Math.round((value + Number.EPSILON) * 1e4) / 1e4;
+}
+function clamp(value, minimum, maximum) {
+	return Math.min(maximum, Math.max(minimum, value));
+}
+function normalizePositiveInteger(value, fallback, maximum) {
+	if (!Number.isFinite(value)) return fallback;
+	return clamp(Math.floor(value ?? fallback), 1, maximum);
+}
+function safeDecode(value) {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return value;
+	}
+}
+function canonicalizeSource(value, baseUrl) {
+	const rawValue = value.trim();
+	let pathname;
+	let hash;
+	let origin = "";
+	try {
+		let configuredBase;
+		if (baseUrl) try {
+			const candidate = new URL(baseUrl);
+			if (candidate.protocol === "http:" || candidate.protocol === "https:") configuredBase = candidate;
+		} catch {}
+		const base = configuredBase ?? new URL("https://docs.local");
+		const parsed = new URL(rawValue, base);
+		pathname = parsed.pathname;
+		hash = parsed.hash;
+		const explicitlySchemed = /^[a-z][a-z\d+.-]*:/iu.test(rawValue);
+		if ((explicitlySchemed && (parsed.protocol === "http:" || parsed.protocol === "https:") || /^[\\/]{2}/u.test(rawValue)) && (!configuredBase || parsed.origin !== configuredBase.origin)) origin = parsed.origin;
+		if (explicitlySchemed && parsed.protocol !== "http:" && parsed.protocol !== "https:") origin = `${parsed.protocol}//${parsed.host}`;
+	} catch {
+		const [pathAndQuery = "/", fragment = ""] = rawValue.split("#", 2);
+		pathname = pathAndQuery.split("?", 1)[0] || "/";
+		hash = fragment ? `#${fragment}` : "";
+	}
+	pathname = pathname.replace(/\/{2,}/gu, "/").replace(/\.md$/iu, "");
+	if (pathname !== "/") pathname = pathname.replace(/\/+$/gu, "");
+	if (!pathname.startsWith("/")) pathname = `/${pathname}`;
+	const normalizedHash = hash ? `#${safeDecode(hash.slice(1)).trim().replace(/^#+/u, "").toLowerCase()}` : "";
+	return `${origin}${pathname || "/"}${normalizedHash === "#" ? "" : normalizedHash}`;
+}
+function sourcePage(value) {
+	return canonicalizeSource(value).split("#", 1)[0] ?? "/";
+}
+function sourceMatches(actual, expected, baseUrl) {
+	const canonicalActual = canonicalizeSource(actual, baseUrl);
+	const canonicalExpected = canonicalizeSource(expected, baseUrl);
+	return canonicalExpected.includes("#") ? canonicalActual === canonicalExpected : sourcePage(canonicalActual) === sourcePage(canonicalExpected);
+}
+function uniqueCanonicalSources(values, baseUrl) {
+	return Array.from(new Set(values.map((value) => canonicalizeSource(value, baseUrl))));
+}
+function valuesOverlap(left, right, matches) {
+	return left.some((leftValue) => right.some((rightValue) => matches(leftValue, rightValue)));
+}
+function getPageScope(page) {
+	const topFramework = normalizeAgentScopeValues(page.framework).map(normalizeAgentFramework);
+	const contractFramework = normalizeAgentScopeValues(page.agent?.appliesTo?.framework).map(normalizeAgentFramework);
+	const topVersion = normalizeAgentScopeValues(page.version).map(normalizeAgentVersion);
+	const contractVersion = normalizeAgentScopeValues(page.agent?.appliesTo?.version).map(normalizeAgentVersion);
+	const locale = normalizeAgentScopeValues(page.locale).map(normalizeAgentLocale);
+	return {
+		framework: Array.from(new Set([...topFramework, ...contractFramework])),
+		version: Array.from(new Set([...topVersion, ...contractVersion])),
+		locale,
+		frameworkAmbiguous: topFramework.length > 0 && contractFramework.length > 0 && !valuesOverlap(topFramework, contractFramework, (left, right) => left === right),
+		versionAmbiguous: topVersion.length > 0 && contractVersion.length > 0 && !valuesOverlap(topVersion, contractVersion, agentVersionConstraintsOverlap)
+	};
+}
+function compareCodePoints(left, right) {
+	if (left === right) return 0;
+	return left < right ? -1 : 1;
+}
+function toGoldenSources(sources, relevantSources, baseUrl) {
+	return sources.map((source, index) => ({
+		rank: index + 1,
+		url: canonicalizeSource(source.url, baseUrl),
+		title: source.section ?? source.title,
+		framework: source.framework,
+		version: source.version,
+		utf8Bytes: source.utf8Bytes,
+		relevant: relevantSources.some((expected) => sourceMatches(source.url, expected, baseUrl)),
+		truncated: source.truncated
+	}));
+}
+function toContextCandidates(sources, pagesByUrl) {
+	return sources.flatMap((source) => {
+		const page = pagesByUrl.get(sourcePage(source.pageUrl));
+		if (!page) return [];
+		return [{
+			page,
+			source: canonicalizeSource(source.url),
+			content: source.content,
+			scope: getPageScope(page)
+		}];
+	});
+}
+function extractRenderedCitations(context, sources) {
+	const actual = [];
+	const blockUtf8Bytes = [];
+	let cursor = 0;
+	let layoutIntegrity = true;
+	for (let index = 0; index < sources.length; index += 1) {
+		const attributableStart = cursor;
+		if (index > 0) {
+			if (!context.startsWith(CONTEXT_SEPARATOR, cursor)) {
+				layoutIntegrity = false;
+				break;
+			}
+			cursor += 7;
+		}
+		const contentMarker = `\n\n${sources[index].content}`;
+		const contentStart = context.indexOf(contentMarker, cursor);
+		if (contentStart < cursor) {
+			layoutIntegrity = false;
+			break;
+		}
+		const sourceLines = context.slice(cursor, contentStart).split(/\r?\n/u).map((line) => line.match(/^Source:\s+(.+)$/u)?.[1]?.trim()).filter((source) => Boolean(source));
+		if (sourceLines.length !== 1) layoutIntegrity = false;
+		actual.push(...sourceLines.map((source) => canonicalizeSource(source)));
+		cursor = contentStart + contentMarker.length;
+		blockUtf8Bytes.push(Buffer.byteLength(context.slice(attributableStart, cursor), "utf8"));
+	}
+	if (cursor !== context.length) layoutIntegrity = false;
+	return {
+		actual,
+		layoutIntegrity,
+		blockUtf8Bytes
+	};
+}
+function getPageAgentMarkdown(page) {
+	return page.agentRawContent ?? page.agentFallbackRawContent ?? page.agentContent ?? page.agentFallbackContent ?? page.rawContent ?? page.content;
+}
+function findPageForSource(pagesByUrl, value) {
+	return pagesByUrl.get(sourcePage(value));
+}
+function getResultAnchor(value) {
+	return canonicalizeSource(value).split("#", 2)[1] || void 0;
+}
+function hydrateSearchSource(result, index, pagesByUrl, contentMode, baseUrl) {
+	const normalizedResultUrl = canonicalizeSource(result.url, baseUrl);
+	const page = findPageForSource(pagesByUrl, normalizedResultUrl);
+	const anchor = getResultAnchor(result.url);
+	const section = anchor ?? result.section;
+	const pageSection = page && section ? findDocsMarkdownSection(getPageAgentMarkdown(page), section) : void 0;
+	const content = contentMode === "page-section" && page ? (pageSection?.content ?? getPageAgentMarkdown(page)).trim() : [result.content, result.description].filter(Boolean).join("\n\n").trim();
+	const scope = page ? getPageScope(page) : void 0;
+	const url = normalizedResultUrl;
+	return {
+		id: result.id || `evaluation-result-${index + 1}`,
+		title: page?.title ?? result.content.split("—", 1)[0]?.trim() ?? url,
+		pageUrl: sourcePage(url),
+		url,
+		section: pageSection?.title ?? result.section,
+		anchor: pageSection?.anchor ?? anchor,
+		sourcePath: page?.sourcePath,
+		lastModified: page?.lastModified,
+		locale: scope?.locale[0],
+		framework: scope?.framework[0],
+		version: scope?.version[0],
+		tags: page?.tags ? [...page.tags] : void 0,
+		score: result.score,
+		content,
+		chars: content.length,
+		utf8Bytes: Buffer.byteLength(content, "utf8"),
+		truncated: false
+	};
+}
+function buildContextFromSources(options) {
+	const blocks = [];
+	const included = [];
+	let usedUtf8Bytes = 0;
+	for (const source of options.sources) {
+		const header = [`## ${source.title}`, `Source: ${source.url}`].join("\n");
+		const separator = blocks.length === 0 ? "" : CONTEXT_SEPARATOR;
+		const available = options.tokenBudget - usedUtf8Bytes - Buffer.byteLength(separator + header + "\n\n");
+		if (available <= 0) break;
+		const contentBuffer = Buffer.from(source.content, "utf8");
+		let content = source.content;
+		let truncated = false;
+		if (contentBuffer.byteLength > available) {
+			truncated = true;
+			content = contentBuffer.subarray(0, available).toString("utf8").replace(/\uFFFD$/u, "");
+			while (Buffer.byteLength(content, "utf8") > available) content = content.slice(0, -1);
+		}
+		if (!content) break;
+		const block = `${header}\n\n${content}`;
+		blocks.push(block);
+		usedUtf8Bytes += Buffer.byteLength(separator + block, "utf8");
+		included.push({
+			...source,
+			content,
+			chars: content.length,
+			utf8Bytes: Buffer.byteLength(content, "utf8"),
+			truncated
+		});
+		if (truncated) break;
+	}
+	const context = blocks.join(CONTEXT_SEPARATOR);
+	usedUtf8Bytes = Buffer.byteLength(context, "utf8");
+	return {
+		query: options.query,
+		filters: {
+			framework: options.filters?.framework,
+			version: options.filters?.version,
+			locale: options.filters?.locale
+		},
+		budget: {
+			requestedTokens: options.tokenBudget,
+			strategy: "utf8-bytes",
+			maxUtf8Bytes: options.tokenBudget,
+			usedUtf8Bytes,
+			conservativeTokenUpperBound: usedUtf8Bytes,
+			remainingUtf8Bytes: Math.max(0, options.tokenBudget - usedUtf8Bytes),
+			truncated: included.some((source) => source.truncated) || included.length < options.sources.length
+		},
+		resultCount: included.length,
+		candidateCount: options.sources.length,
+		context,
+		sources: included
+	};
+}
+function getConfiguredSearchProvider(search) {
+	if (search === false) return "disabled";
+	if (!search || search === true) return "simple";
+	if (search.enabled === false) return "disabled";
+	return search.provider ?? "simple";
+}
+function isConfiguredSearchDisabled(search) {
+	return search === false || Boolean(search && typeof search === "object" && search.enabled === false);
+}
+function assertEvaluationSearchConfig(search) {
+	if (search === void 0 || typeof search === "boolean") return;
+	if (!isRecord(search)) throw new Error("The configured search value must be a boolean or provider object.");
+	const runtime = search;
+	if (runtime.enabled !== void 0 && typeof runtime.enabled !== "boolean") throw new Error("The configured search enabled field must be boolean.");
+	const provider = runtime.provider ?? "simple";
+	if (typeof provider !== "string" || ![
+		"simple",
+		"custom",
+		"typesense",
+		"mcp",
+		"algolia"
+	].includes(provider)) throw new Error(`Unsupported configured search provider: ${String(provider)}.`);
+	const requireStrings = (fields) => {
+		const missing = fields.filter((field) => typeof runtime[field] !== "string" || !runtime[field].trim());
+		if (missing.length > 0) throw new Error(`The ${provider} search provider requires non-empty ${missing.join(", ")}.`);
+	};
+	if (provider === "mcp") {
+		requireStrings(["endpoint"]);
+		if (runtime.headers !== void 0 && (!isRecord(runtime.headers) || Object.values(runtime.headers).some((value) => typeof value !== "string"))) throw new Error("The MCP search provider headers must contain only string values.");
+	}
+	if (provider === "algolia") requireStrings([
+		"appId",
+		"indexName",
+		"searchApiKey"
+	]);
+	if (provider === "typesense") requireStrings([
+		"baseUrl",
+		"collection",
+		"apiKey"
+	]);
+	if (provider === "custom") {
+		const adapter = runtime.adapter;
+		if (typeof adapter !== "function" && (!isRecord(adapter) || typeof adapter.search !== "function")) throw new Error("The custom search provider requires an adapter or adapter factory with a search function.");
+	}
+}
+function assertEvaluationSearchAllowed(search, allowNetwork, surface, baseUrl) {
+	const provider = getConfiguredSearchProvider(search);
+	if (surface === "configured-search" && provider === "disabled") throw new Error("Configured search is disabled; no search surface can be evaluated.");
+	if (provider !== "simple" && provider !== "disabled" && !allowNetwork) throw new Error(`The ${provider} search provider requires agent.evaluations.allowNetwork: true for evaluation.`);
+	if (search && typeof search === "object" && search.provider === "mcp" && !/^https?:\/\//iu.test(search.endpoint) && !baseUrl) throw new Error("A relative MCP evaluation endpoint requires ai.docsUrl or another canonical docs baseUrl.");
+}
+async function runEvaluationSearchWithTimeout(options) {
+	if (options.timeoutMs !== void 0 && (typeof options.timeoutMs !== "number" || !Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0)) throw new Error("The agent evaluation searchTimeoutMs must be a positive finite number.");
+	const timeoutMs = normalizePositiveInteger(options.timeoutMs, 3e4, 3e5);
+	const controller = new AbortController();
+	let timeout;
+	let timeoutError;
+	const timedOut = new Promise((_, reject) => {
+		timeout = setTimeout(() => {
+			timeoutError = /* @__PURE__ */ new Error(`The ${options.provider} search provider timed out after ${timeoutMs}ms.`);
+			controller.abort();
+			reject(timeoutError);
+		}, timeoutMs);
+	});
+	try {
+		return await Promise.race([Promise.resolve().then(() => options.run(controller.signal)), timedOut]).catch((error) => {
+			if (timeoutError) throw timeoutError;
+			throw error;
+		});
+	} finally {
+		if (timeout) clearTimeout(timeout);
+	}
+}
+function createContextShell(options) {
+	const context = options.context ?? "";
+	const sources = options.sources ?? [];
+	const usedUtf8Bytes = Buffer.byteLength(context, "utf8");
+	return {
+		query: options.query,
+		filters: {
+			framework: options.filters?.framework,
+			version: options.filters?.version,
+			locale: options.filters?.locale
+		},
+		budget: {
+			requestedTokens: options.tokenBudget,
+			strategy: "utf8-bytes",
+			maxUtf8Bytes: options.tokenBudget,
+			usedUtf8Bytes,
+			conservativeTokenUpperBound: usedUtf8Bytes,
+			remainingUtf8Bytes: Math.max(0, options.tokenBudget - usedUtf8Bytes),
+			truncated: options.truncated ?? usedUtf8Bytes > options.tokenBudget
+		},
+		resultCount: sources.length,
+		candidateCount: options.candidateCount ?? sources.length,
+		context,
+		sources
+	};
+}
+function parseAskAIContextSources(options) {
+	if (!options.context) return {
+		sources: [],
+		citations: [],
+		integrity: options.results.length === 0
+	};
+	const blocks = options.blocks;
+	const sources = [];
+	const citations = [];
+	let integrity = blocks.length === options.results.length && blocks.join(CONTEXT_SEPARATOR) === options.context;
+	for (let index = 0; index < blocks.length; index += 1) {
+		const block = blocks[index] ?? "";
+		const contentStart = block.indexOf("\n\n");
+		if (contentStart < 0) {
+			integrity = false;
+			continue;
+		}
+		const urlLines = block.slice(0, contentStart).split(/\r?\n/u).map((line) => line.match(/^URL:\s+(.+)$/u)?.[1]?.trim()).filter((value) => Boolean(value));
+		if (urlLines.length !== 1) integrity = false;
+		const url = canonicalizeSource(urlLines[0] ?? "/", options.baseUrl);
+		const expected = options.results[index];
+		if (!expected || !sourceMatches(url, expected.url) || canonicalizeSource(expected.url) !== url) integrity = false;
+		const content = block.slice(contentStart + 2);
+		const base = expected ?? {
+			id: `ask-ai-result-${index + 1}`,
+			title: url,
+			pageUrl: sourcePage(url),
+			url,
+			content: "",
+			chars: 0,
+			utf8Bytes: 0,
+			truncated: false
+		};
+		citations.push(url);
+		sources.push({
+			...base,
+			url,
+			pageUrl: sourcePage(url),
+			content,
+			chars: content.length,
+			utf8Bytes: Buffer.byteLength(content, "utf8"),
+			truncated: content !== base.content
+		});
+	}
+	return {
+		sources,
+		citations,
+		integrity
+	};
+}
+async function buildGoldenSurface(options) {
+	const surface = options.task.surface ?? options.runOptions.surface ?? "mcp-context";
+	const orderedPages = options.pages.slice().sort((left, right) => compareCodePoints(canonicalizeSource(left.url), canonicalizeSource(right.url)));
+	const pagesByUrl = new Map(orderedPages.map((page) => [sourcePage(page.url), page]));
+	if (surface === "mcp-context") {
+		const contextOptions = {
+			pages: orderedPages,
+			query: options.task.query,
+			framework: options.task.filters?.framework,
+			version: options.task.filters?.version,
+			locale: options.task.filters?.locale,
+			maxResults: options.topK
+		};
+		const [rankedContext, budgetedContext] = await Promise.all([buildDocsMcpContext({
+			...contextOptions,
+			tokenBudget: Number.MAX_SAFE_INTEGER
+		}), buildDocsMcpContext({
+			...contextOptions,
+			tokenBudget: options.tokenBudget
+		})]);
+		const extracted = extractRenderedCitations(budgetedContext.context, budgetedContext.sources);
+		return {
+			surface,
+			provider: "simple",
+			rankedContext,
+			budgetedContext,
+			citationEvidence: {
+				mode: "context",
+				actual: extracted.actual,
+				integrity: extracted.layoutIntegrity
+			}
+		};
+	}
+	const configuredSurfaceSearch = surface === "ask-ai-context" ? options.runOptions.askAISearch ?? options.runOptions.search : options.runOptions.search;
+	const effectiveSurfaceSearch = surface === "ask-ai-context" && isConfiguredSearchDisabled(configuredSurfaceSearch) ? true : configuredSurfaceSearch;
+	assertEvaluationSearchConfig(effectiveSurfaceSearch);
+	const surfaceSearch = resolveSearchRequestConfig(effectiveSurfaceSearch, options.runOptions.baseUrl);
+	assertEvaluationSearchAllowed(surfaceSearch, options.runOptions.allowNetwork === true, surface, options.runOptions.baseUrl);
+	const provider = getConfiguredSearchProvider(surfaceSearch);
+	if (surface === "configured-search") {
+		const results = await runEvaluationSearchWithTimeout({
+			provider,
+			timeoutMs: options.runOptions.searchTimeoutMs,
+			run: (signal) => performDocsSearch({
+				pages: orderedPages,
+				query: options.task.query,
+				search: surfaceSearch,
+				audience: "agent",
+				locale: options.task.filters?.locale,
+				siteTitle: options.runOptions.siteTitle,
+				baseUrl: options.runOptions.baseUrl,
+				limit: options.topK,
+				failureMode: "throw",
+				supplementExternalResults: false,
+				strictExternalOrigins: true,
+				signal
+			})
+		});
+		const rankedSources = results.slice(0, options.topK).map((result, index) => hydrateSearchSource(result, index, pagesByUrl, "result", options.runOptions.baseUrl));
+		return {
+			surface,
+			provider,
+			rankedContext: buildContextFromSources({
+				query: options.task.query,
+				filters: options.task.filters,
+				sources: rankedSources,
+				tokenBudget: Number.MAX_SAFE_INTEGER
+			}),
+			budgetedContext: buildContextFromSources({
+				query: options.task.query,
+				filters: options.task.filters,
+				sources: rankedSources,
+				tokenBudget: options.tokenBudget
+			}),
+			citationEvidence: {
+				mode: "results",
+				actual: rankedSources.map((source) => canonicalizeSource(source.url)),
+				integrity: rankedSources.every((source, index) => source.url === canonicalizeSource(results[index]?.url ?? "", options.runOptions.baseUrl))
+			}
+		};
+	}
+	const askAI = await runEvaluationSearchWithTimeout({
+		provider,
+		timeoutMs: options.runOptions.searchTimeoutMs,
+		run: (signal) => buildDocsAskAIContext({
+			pages: orderedPages,
+			query: options.task.query,
+			search: surfaceSearch,
+			locale: options.task.filters?.locale,
+			siteTitle: options.runOptions.siteTitle,
+			baseUrl: options.runOptions.baseUrl,
+			limit: options.topK,
+			maxContextChars: options.tokenBudget,
+			searchFailureMode: "throw",
+			strictExternalOrigins: true,
+			signal
+		})
+	});
+	const rankedSources = askAI.searchResults.slice(0, options.topK).map((result, index) => hydrateSearchSource(result, index, pagesByUrl, "result", options.runOptions.baseUrl));
+	const resultSources = askAI.results.map((result, index) => hydrateSearchSource(result, index, pagesByUrl, "page-section", options.runOptions.baseUrl));
+	const parsed = parseAskAIContextSources({
+		context: askAI.context,
+		blocks: askAI.blocks.map((block) => block.text),
+		results: resultSources,
+		baseUrl: options.runOptions.baseUrl
+	});
+	return {
+		surface,
+		provider,
+		rankedContext: createContextShell({
+			query: options.task.query,
+			filters: options.task.filters,
+			tokenBudget: Number.MAX_SAFE_INTEGER,
+			sources: rankedSources
+		}),
+		budgetedContext: createContextShell({
+			query: options.task.query,
+			filters: options.task.filters,
+			tokenBudget: options.tokenBudget,
+			context: askAI.context,
+			sources: parsed.sources,
+			candidateCount: askAI.results.length,
+			truncated: parsed.sources.some((source) => source.truncated) || Buffer.byteLength(askAI.context, "utf8") > options.tokenBudget
+		}),
+		citationEvidence: {
+			mode: "context",
+			actual: parsed.citations,
+			integrity: parsed.integrity
+		},
+		attributionUtf8Bytes: askAI.blocks.map((block, index) => Buffer.byteLength(`${index === 0 ? "" : CONTEXT_SEPARATOR}${block.text}`, "utf8"))
+	};
+}
+function validateStaticSyntax(target) {
+	const language = target.language?.toLowerCase();
+	if (language === "json") try {
+		JSON.parse(target.code);
+		return {
+			supported: true,
+			valid: true
+		};
+	} catch {
+		return {
+			supported: true,
+			valid: false
+		};
+	}
+	if (language === "javascript" || language === "js" || language === "jsx" || language === "node" || language === "typescript" || language === "ts" || language === "tsx") try {
+		const typescript = language === "typescript" || language === "ts" || language === "tsx";
+		const jsx = language === "jsx" || language === "tsx";
+		const transformed = STATIC_JITI.transform({
+			source: target.code,
+			filename: `golden-example.${language === "typescript" ? "ts" : language}`,
+			ts: typescript,
+			jsx,
+			async: true
+		});
+		return {
+			supported: true,
+			valid: !/\bexports\.__JITI_ERROR__\s*=/u.test(transformed)
+		};
+	} catch {
+		return {
+			supported: true,
+			valid: false
+		};
+	}
+	return {
+		supported: false,
+		valid: false
+	};
+}
+async function collectRetrievedExamples(candidates) {
+	const examples = [];
+	for (const candidate of candidates) {
+		const targets = extractCodeBlocksFromMarkdown({
+			source: candidate.content,
+			filePath: candidate.page.sourcePath ?? candidate.page.slug,
+			relativePath: candidate.page.slug
+		});
+		for (const target of targets) examples.push({
+			source: candidate.source,
+			originalId: target.id,
+			target: {
+				...target,
+				id: `${canonicalizeSource(candidate.source)}::${target.id}`
+			}
+		});
+	}
+	const plans = await planCodeBlockTargets(examples.map((example) => example.target), STATIC_CODE_PLAN_CONFIG);
+	return examples.map((example, index) => ({
+		...example,
+		plan: plans[index],
+		...(() => {
+			const syntax = validateStaticSyntax(example.target);
+			const structurallyComplete = Boolean(example.target.code.trim()) && !example.target.code.split("\n").some((line) => /^\s*(?:(?:\/\/|#)\s*)?\.\.\.\s*$/u.test(line));
+			return {
+				syntaxSupported: syntax.supported,
+				syntaxValid: syntax.valid && structurallyComplete,
+				staticExecutable: example.target.runnable && Boolean(example.target.language) && EXECUTABLE_LANGUAGES.has(example.target.language.toLowerCase()) && plans[index]?.action !== "skip" && structurallyComplete && (!syntax.supported || syntax.valid)
+			};
+		})()
+	}));
+}
+function normalizedEqual(left, right) {
+	return (left ?? "").trim().toLowerCase() === (right ?? "").trim().toLowerCase();
+}
+function exampleMetadataMatches(expected, actual, baseUrl) {
+	if (expected.source && !sourceMatches(actual.source, expected.source, baseUrl)) return false;
+	if (expected.language && !normalizedEqual(actual.target.language, expected.language)) return false;
+	if (expected.framework && !normalizedEqual(actual.target.framework, expected.framework)) return false;
+	if (expected.packageManager && !normalizedEqual(actual.target.packageManager, expected.packageManager)) return false;
+	if (expected.title && !normalizedEqual(actual.target.title, expected.title)) return false;
+	if (expected.includes?.some((fragment) => !actual.target.code.includes(fragment))) return false;
+	if (expected.runnable === false) return !actual.target.runnable;
+	return actual.target.runnable;
+}
+function resolveExampleVerification(expected) {
+	return expected.verification ?? (expected.runnable === false ? "present" : "syntax");
+}
+function failedExampleResult(expected, verification, reason, status = "failed") {
+	return {
+		expected,
+		verification,
+		status,
+		reason,
+		syntaxValid: false,
+		executed: false,
+		executable: false,
+		passed: false
+	};
+}
+async function evaluateExamples(expectedExamples, candidates, options) {
+	const actualExamples = await collectRetrievedExamples(candidates);
+	const claimed = /* @__PURE__ */ new Set();
+	const matches = expectedExamples.map((expected) => {
+		const index = actualExamples.findIndex((example, candidateIndex) => !claimed.has(candidateIndex) && exampleMetadataMatches(expected, example, options.baseUrl));
+		const verification = resolveExampleVerification(expected);
+		if (index < 0) return {
+			expected,
+			verification,
+			result: failedExampleResult(expected, verification, "No matching code block was retrieved.")
+		};
+		claimed.add(index);
+		return {
+			expected,
+			verification,
+			matched: actualExamples[index]
+		};
+	});
+	const executeMatches = matches.filter((match) => match.verification === "execute" && Boolean(match.matched));
+	const executionByTarget = /* @__PURE__ */ new Map();
+	let executionFailure;
+	if (executeMatches.length > 0) {
+		const resolved = resolveDocsCodeBlocksValidateConfig(options.codeBlocksValidate);
+		if (options.allowNetwork !== true) executionFailure = "Execution verification requires agent.evaluations.allowNetwork: true because arbitrary examples and validators may access the network.";
+		else if (!resolved.enabled) executionFailure = "Execution verification requires codeBlocks.validate to be explicitly enabled.";
+		else if (resolved.mode !== "report") executionFailure = "Execution verification requires codeBlocks.validate.mode to be report.";
+		else if (!options.rootDir) executionFailure = "Execution verification requires a project rootDir.";
+		else try {
+			const targets = executeMatches.map((match) => match.matched.target);
+			const plans = await planCodeBlockTargets(targets, resolved);
+			const validation = await validateCodeBlockPlans({
+				plans,
+				rootDir: options.rootDir,
+				config: resolved
+			});
+			for (let index = 0; index < targets.length; index += 1) {
+				const plan = plans[index];
+				const result = validation.find((candidate) => candidate.plan === plan);
+				if (result) executionByTarget.set(targets[index], result);
+			}
+		} catch (error) {
+			executionFailure = `Execution verification failed: ${error instanceof Error ? error.message : String(error)}`;
+		}
+	}
+	const results = matches.map(({ expected, verification, matched }) => {
+		if (!matched) return failedExampleResult(expected, verification, "No matching code block was retrieved.");
+		const base = {
+			expected,
+			matchedId: matched.originalId,
+			source: matched.source,
+			verification,
+			syntaxValid: matched.syntaxValid,
+			executed: false,
+			executable: matched.staticExecutable
+		};
+		if (verification === "present") return {
+			...base,
+			status: "passed",
+			passed: true
+		};
+		if (verification === "syntax") {
+			if (!matched.syntaxSupported) return {
+				...base,
+				status: "skipped",
+				reason: `Static syntax verification is unsupported for ${matched.target.language ?? "an untyped fence"}.`,
+				passed: false
+			};
+			return {
+				...base,
+				status: matched.syntaxValid ? "passed" : "failed",
+				reason: matched.syntaxValid ? void 0 : "The retrieved code block has invalid syntax.",
+				passed: matched.syntaxValid
+			};
+		}
+		if (executionFailure) return {
+			...base,
+			status: "skipped",
+			reason: executionFailure,
+			passed: false
+		};
+		const validation = executionByTarget.get(matched.target);
+		if (!validation) return {
+			...base,
+			status: "skipped",
+			reason: "The configured validator did not return an execution result.",
+			passed: false
+		};
+		const executed = validation.plan.action === "execute" && validation.status === "PASS";
+		return {
+			...base,
+			status: executed ? "passed" : validation.status === "SKIP" ? "skipped" : "failed",
+			reason: executed ? void 0 : validation.reason ?? (validation.plan.action !== "execute" ? "The validator did not plan runtime execution." : `Execution returned ${validation.status}.`),
+			executed,
+			executable: matched.staticExecutable,
+			executionStatus: validation.status,
+			passed: executed
+		};
+	});
+	const matched = results.filter((result) => result.passed).length;
+	return {
+		expected: expectedExamples.length,
+		matched,
+		syntaxValid: results.filter((result) => result.syntaxValid).length,
+		executed: results.filter((result) => result.executed).length,
+		executable: results.filter((result) => result.executable).length,
+		results,
+		passed: matched === expectedExamples.length
+	};
+}
+function buildRetrievalMetrics(task, sources, topK, baseUrl) {
+	const expected = uniqueCanonicalSources(task.expect.relevantSources, baseUrl);
+	const forbidden = uniqueCanonicalSources(task.expect.forbiddenSources ?? [], baseUrl);
+	const retrievedRelevant = expected.filter((source) => sources.some((actual) => sourceMatches(actual.url, source, baseUrl))).length;
+	const recallAtK = expected.length > 0 ? retrievedRelevant / expected.length : 0;
+	const firstRelevant = sources.find((source) => source.relevant)?.rank ?? null;
+	const forbiddenSources = sources.filter((source) => forbidden.some((forbiddenSource) => sourceMatches(source.url, forbiddenSource, baseUrl))).map((source) => source.url);
+	const minimumRecall = clamp(task.expect.minRecallAtK ?? 1, 0, 1);
+	const maximumRank = normalizePositiveInteger(task.expect.maxFirstRelevantRank, topK, topK);
+	return {
+		expectedRelevant: expected.length,
+		retrievedRelevant,
+		recallAtK: round(recallAtK),
+		firstRelevantRank: firstRelevant,
+		reciprocalRank: firstRelevant ? round(1 / firstRelevant) : 0,
+		forbiddenSources,
+		passed: expected.length > 0 && recallAtK >= minimumRecall && firstRelevant !== null && firstRelevant <= maximumRank && forbiddenSources.length === 0
+	};
+}
+function buildCitationMetrics(task, context, sources, evidence, baseUrl) {
+	const expected = uniqueCanonicalSources(task.expect.requiredCitations ?? task.expect.relevantSources, baseUrl);
+	const allowed = uniqueCanonicalSources([
+		...task.expect.relevantSources,
+		...task.expect.requiredCitations ?? [],
+		...task.expect.allowedSources ?? []
+	], baseUrl);
+	const extracted = evidence ? {
+		actual: evidence.actual,
+		layoutIntegrity: evidence.integrity
+	} : extractRenderedCitations(context, sources);
+	const actual = extracted.actual;
+	const sourceRecords = sources.map((source) => canonicalizeSource(source.url));
+	const missing = expected.filter((expectedSource) => !actual.some((actualSource) => sourceMatches(actualSource, expectedSource, baseUrl)));
+	const unexpected = actual.filter((actualSource) => !allowed.some((allowedSource) => sourceMatches(actualSource, allowedSource, baseUrl)));
+	const correct = actual.filter((actualSource) => allowed.some((allowedSource) => sourceMatches(actualSource, allowedSource, baseUrl))).length;
+	const matchedExpected = expected.filter((expectedSource) => actual.some((actualSource) => sourceMatches(actualSource, expectedSource, baseUrl))).length;
+	const precision = actual.length > 0 ? correct / actual.length : expected.length === 0 ? 1 : 0;
+	const recall = expected.length > 0 ? matchedExpected / expected.length : 1;
+	const integrity = extracted.layoutIntegrity && actual.length === sourceRecords.length && actual.every((source, index) => source === sourceRecords[index]);
+	return {
+		evidence: evidence?.mode ?? "context",
+		expected,
+		actual,
+		missing,
+		unexpected,
+		precision: round(precision),
+		recall: round(recall),
+		integrity,
+		passed: missing.length === 0 && unexpected.length === 0 && integrity
+	};
+}
+function canonicalizeAnswerCitation(value, baseUrl) {
+	return canonicalizeSource(value.trim(), baseUrl);
+}
+function uniqueAnswerCitations(values, baseUrl) {
+	return Array.from(new Set(values.map((value) => canonicalizeAnswerCitation(value, baseUrl))));
+}
+function answerCitationMatches(actual, expected) {
+	return expected.includes("#") ? actual === expected : actual.split("#", 1)[0] === expected.split("#", 1)[0];
+}
+function maskMarkdownCitationInertRegions(text) {
+	const masked = new Uint8Array(text.length);
+	const maskRange = (start, end) => {
+		for (let index = start; index < end; index += 1) masked[index] = 1;
+	};
+	for (let start = text.indexOf("<!--"); start >= 0; start = text.indexOf("<!--", start + 4)) {
+		const closing = text.indexOf("-->", start + 4);
+		const end = closing < 0 ? text.length : closing + 3;
+		maskRange(start, end);
+		if (closing < 0) break;
+		start = closing;
+	}
+	let openFence;
+	let lineStart = 0;
+	while (lineStart <= text.length) {
+		const newline = text.indexOf("\n", lineStart);
+		const lineEnd = newline < 0 ? text.length : newline + 1;
+		const line = text.slice(lineStart, newline < 0 ? text.length : newline);
+		if (!masked[lineStart]) {
+			if (!openFence) {
+				const opening = line.match(/^[ \t]{0,3}(`{3,}|~{3,})/u)?.[1];
+				if (opening) openFence = {
+					character: opening[0],
+					length: opening.length,
+					start: lineStart
+				};
+			} else if (new RegExp(`^[ \\t]{0,3}${openFence.character}{${openFence.length},}[ \\t]*$`, "u").test(line)) {
+				maskRange(openFence.start, lineEnd);
+				openFence = void 0;
+			}
+		}
+		if (newline < 0) break;
+		lineStart = lineEnd;
+	}
+	if (openFence) maskRange(openFence.start, text.length);
+	for (let index = 0; index < text.length; index += 1) {
+		if (masked[index] || text[index] !== "`") continue;
+		let runEnd = index + 1;
+		while (!masked[runEnd] && text[runEnd] === "`") runEnd += 1;
+		const runLength = runEnd - index;
+		let cursor = runEnd;
+		let closingEnd = -1;
+		while (cursor < text.length) {
+			if (masked[cursor] || text[cursor] !== "`") {
+				cursor += 1;
+				continue;
+			}
+			let candidateEnd = cursor + 1;
+			while (!masked[candidateEnd] && text[candidateEnd] === "`") candidateEnd += 1;
+			if (candidateEnd - cursor === runLength) {
+				closingEnd = candidateEnd;
+				break;
+			}
+			cursor = candidateEnd;
+		}
+		if (closingEnd > 0) {
+			maskRange(index, closingEnd);
+			index = closingEnd - 1;
+		} else index = runEnd - 1;
+	}
+	return text.split("").map((character, index) => masked[index] && character !== "\n" && character !== "\r" ? " " : character).join("");
+}
+function extractInlineMarkdownLinkDestinations(text) {
+	text = maskMarkdownCitationInertRegions(text);
+	const destinations = [];
+	const escapedAt = (index) => {
+		let backslashes = 0;
+		for (let cursor = index - 1; cursor >= 0 && text[cursor] === "\\"; cursor -= 1) backslashes += 1;
+		return backslashes % 2 === 1;
+	};
+	for (let index = 0; index < text.length - 1; index += 1) {
+		if (text[index] !== "]" || text[index + 1] !== "(" || escapedAt(index)) continue;
+		let bracketDepth = 1;
+		let openingBracket = -1;
+		for (let cursor = index - 1; cursor >= 0; cursor -= 1) {
+			if (escapedAt(cursor)) continue;
+			if (text[cursor] === "]") bracketDepth += 1;
+			if (text[cursor] === "[") {
+				bracketDepth -= 1;
+				if (bracketDepth === 0) {
+					openingBracket = cursor;
+					break;
+				}
+			}
+		}
+		if (openingBracket < 0 || text[openingBracket - 1] === "!" && !escapedAt(openingBracket - 1)) continue;
+		let cursor = index + 2;
+		while (/\s/u.test(text[cursor] ?? "")) cursor += 1;
+		if (text[cursor] === "<") {
+			const end = text.indexOf(">", cursor + 1);
+			if (end <= cursor + 1) continue;
+			let closingCursor = end + 1;
+			while (/\s/u.test(text[closingCursor] ?? "")) closingCursor += 1;
+			const titleOpener = text[closingCursor];
+			if (titleOpener === "\"" || titleOpener === "'" || titleOpener === "(") {
+				const titleCloser = titleOpener === "(" ? ")" : titleOpener;
+				closingCursor += 1;
+				let escaped = false;
+				while (closingCursor < text.length) {
+					const character = text[closingCursor] ?? "";
+					if (escaped) escaped = false;
+					else if (character === "\\") escaped = true;
+					else if (character === titleCloser) {
+						closingCursor += 1;
+						break;
+					}
+					closingCursor += 1;
+				}
+				while (/\s/u.test(text[closingCursor] ?? "")) closingCursor += 1;
+			}
+			if (text[closingCursor] === ")") destinations.push(text.slice(cursor + 1, end));
+			continue;
+		}
+		const start = cursor;
+		let depth = 1;
+		let escaped = false;
+		let destinationEnd = -1;
+		for (; cursor < text.length; cursor += 1) {
+			const character = text[cursor] ?? "";
+			if (escaped) {
+				escaped = false;
+				continue;
+			}
+			if (character === "\\") {
+				escaped = true;
+				continue;
+			}
+			if (character === "(") depth += 1;
+			if (character === ")") {
+				depth -= 1;
+				if (depth === 0) {
+					destinationEnd = cursor;
+					break;
+				}
+			}
+		}
+		if (destinationEnd <= start) continue;
+		const destination = text.slice(start, destinationEnd).trim().match(/^(\S+)/u)?.[1];
+		if (destination) destinations.push(destination.replace(/\\([()])/gu, "$1"));
+	}
+	return destinations;
+}
+function extractAnswerCitations(answer, baseUrl) {
+	const values = [...answer.citations ?? []];
+	for (const destination of extractInlineMarkdownLinkDestinations(answer.text)) {
+		const value = destination.trim();
+		const explicitlyReferenced = /^[a-z][a-z\d+.-]*:/iu.test(value) || /^[\\/]{2}/u.test(value);
+		let isHttpReference = false;
+		if (explicitlyReferenced) try {
+			let parsedBase = new URL("https://docs.local");
+			if (baseUrl) try {
+				const candidate = new URL(baseUrl);
+				if (candidate.protocol === "http:" || candidate.protocol === "https:") parsedBase = candidate;
+			} catch {}
+			const parsed = new URL(value, parsedBase);
+			isHttpReference = parsed.protocol === "http:" || parsed.protocol === "https:";
+		} catch {}
+		if (value && (value.startsWith("/") || isHttpReference)) values.push(value);
+	}
+	return uniqueAnswerCitations(values, baseUrl);
+}
+function buildAnswerMetrics(task, answer, baseUrl) {
+	const expectation = task.expect.answer;
+	if (!expectation) return {
+		evidence: "answer",
+		expected: false,
+		provided: Boolean(answer),
+		textIncludesMissing: [],
+		textExcludesPresent: [],
+		citations: answer ? extractAnswerCitations(answer, baseUrl) : [],
+		requiredCitations: [],
+		missingCitations: [],
+		unexpectedCitations: [],
+		forbiddenCitations: [],
+		passed: true
+	};
+	const text = answer?.text ?? "";
+	const citations = answer ? extractAnswerCitations(answer, baseUrl) : [];
+	const requiredCitations = uniqueAnswerCitations(expectation.requiredCitations ?? task.expect.requiredCitations ?? task.expect.relevantSources, baseUrl);
+	const allowed = uniqueAnswerCitations([
+		...task.expect.relevantSources,
+		...task.expect.requiredCitations ?? [],
+		...task.expect.allowedSources ?? [],
+		...requiredCitations,
+		...expectation.allowedCitations ?? []
+	], baseUrl);
+	const forbiddenExpected = uniqueAnswerCitations([...task.expect.forbiddenSources ?? [], ...expectation.forbiddenCitations ?? []], baseUrl);
+	const textIncludesMissing = (expectation.includes ?? []).filter((fragment) => !text.includes(fragment));
+	const textExcludesPresent = (expectation.excludes ?? []).filter((fragment) => text.includes(fragment));
+	const missingCitations = requiredCitations.filter((expected) => !citations.some((citation) => answerCitationMatches(citation, expected)));
+	const unexpectedCitations = citations.filter((citation) => !allowed.some((allowedSource) => answerCitationMatches(citation, allowedSource)));
+	const forbiddenCitations = citations.filter((citation) => forbiddenExpected.some((forbidden) => answerCitationMatches(citation, forbidden)));
+	return {
+		evidence: "answer",
+		expected: true,
+		provided: Boolean(answer),
+		textIncludesMissing,
+		textExcludesPresent,
+		citations,
+		requiredCitations,
+		missingCitations,
+		unexpectedCitations,
+		forbiddenCitations,
+		passed: Boolean(answer) && textIncludesMissing.length === 0 && textExcludesPresent.length === 0 && missingCitations.length === 0 && unexpectedCitations.length === 0 && forbiddenCitations.length === 0
+	};
+}
+function normalizeAnswerResult(value) {
+	if (!isRecord(value) || typeof value.text !== "string" || !value.text.trim()) throw new Error("The answer runner must return { text: string, citations?: string[] }.");
+	if (value.citations !== void 0 && (!Array.isArray(value.citations) || value.citations.some((citation) => typeof citation !== "string" || !citation.trim()))) throw new Error("The answer runner citations field must contain only non-empty strings.");
+	return {
+		text: value.text,
+		citations: Array.isArray(value.citations) ? value.citations : void 0
+	};
+}
+async function readResponseTextWithLimit(response, maxBytes, controller) {
+	if (!response.body) return "";
+	const reader = response.body.getReader();
+	const decoder = new TextDecoder();
+	const chunks = [];
+	let bytes = 0;
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			bytes += value.byteLength;
+			if (bytes > maxBytes) {
+				controller.abort();
+				await reader.cancel().catch(() => void 0);
+				throw new Error("The HTTP answer provider response exceeds the 1 MB limit.");
+			}
+			chunks.push(decoder.decode(value, { stream: true }));
+		}
+		chunks.push(decoder.decode());
+		return chunks.join("");
+	} finally {
+		reader.releaseLock();
+	}
+}
+async function runAnswerProvider(options) {
+	if (!isRecord(options.provider)) throw new Error("The answer provider must be a callback or HTTP provider object.");
+	const provider = options.provider.provider;
+	if (provider !== "callback" && provider !== "http") throw new Error("The answer provider must set provider to \"callback\" or \"http\".");
+	const timeoutValue = options.provider.timeoutMs;
+	if (timeoutValue !== void 0 && (typeof timeoutValue !== "number" || !Number.isFinite(timeoutValue) || timeoutValue <= 0)) throw new Error("The answer provider timeoutMs must be a positive finite number.");
+	const timeoutMs = normalizePositiveInteger(typeof timeoutValue === "number" ? timeoutValue : void 0, 3e4, 3e5);
+	const controller = new AbortController();
+	let timeout;
+	let timeoutError;
+	const timedOut = new Promise((_, reject) => {
+		timeout = setTimeout(() => {
+			timeoutError = /* @__PURE__ */ new Error(`The ${provider} answer provider timed out after ${timeoutMs}ms.`);
+			controller.abort();
+			reject(timeoutError);
+		}, timeoutMs);
+	});
+	if (provider === "callback") {
+		if (typeof options.provider.run !== "function") {
+			if (timeout) clearTimeout(timeout);
+			throw new Error("The callback answer provider requires a callable run function.");
+		}
+		try {
+			return normalizeAnswerResult(await Promise.race([Promise.resolve(options.provider.run({
+				...options.input,
+				signal: controller.signal
+			})), timedOut]).catch((error) => {
+				if (timeoutError) throw timeoutError;
+				throw error;
+			}));
+		} finally {
+			if (timeout) clearTimeout(timeout);
+		}
+	}
+	if (!options.allowNetwork) {
+		if (timeout) clearTimeout(timeout);
+		throw new Error("The HTTP answer provider requires agent.evaluations.allowNetwork: true for evaluation.");
+	}
+	if (typeof options.provider.endpoint !== "string" || !options.provider.endpoint.trim()) {
+		if (timeout) clearTimeout(timeout);
+		throw new Error("The HTTP answer provider requires a non-empty endpoint.");
+	}
+	let endpoint;
+	try {
+		endpoint = new URL(options.provider.endpoint);
+	} catch {
+		if (timeout) clearTimeout(timeout);
+		throw new Error("The HTTP answer provider endpoint must be an absolute HTTP(S) URL.");
+	}
+	if (endpoint.protocol !== "http:" && endpoint.protocol !== "https:") {
+		if (timeout) clearTimeout(timeout);
+		throw new Error("The HTTP answer provider endpoint must use HTTP or HTTPS.");
+	}
+	const rawHeaders = options.provider.headers;
+	if (rawHeaders !== void 0 && (!isRecord(rawHeaders) || Object.values(rawHeaders).some((value) => typeof value !== "string"))) {
+		if (timeout) clearTimeout(timeout);
+		throw new Error("The HTTP answer provider headers must contain only string values.");
+	}
+	try {
+		const headers = new Headers(rawHeaders);
+		headers.set("content-type", "application/json");
+		return await Promise.race([(async () => {
+			const response = await fetch(endpoint, {
+				method: "POST",
+				headers,
+				body: JSON.stringify(options.input),
+				signal: controller.signal
+			});
+			if (!response.ok) throw new Error(`The HTTP answer provider returned ${response.status}.`);
+			const contentLength = Number(response.headers.get("content-length"));
+			const maxResponseBytes = 1e6;
+			if (Number.isFinite(contentLength) && contentLength > maxResponseBytes) throw new Error("The HTTP answer provider response exceeds the 1 MB limit.");
+			const responseText = await readResponseTextWithLimit(response, maxResponseBytes, controller);
+			let payload;
+			try {
+				payload = JSON.parse(responseText);
+			} catch {
+				throw new Error("The HTTP answer provider must return valid JSON.");
+			}
+			return normalizeAnswerResult(payload);
+		})(), timedOut]).catch((error) => {
+			if (timeoutError) throw timeoutError;
+			throw error;
+		});
+	} finally {
+		if (timeout) clearTimeout(timeout);
+	}
+}
+function buildSelectionMetrics(task, sources, pagesByUrl) {
+	const requestedFramework = task.filters?.framework;
+	const requestedVersion = task.filters?.version;
+	const requestedLocale = task.filters?.locale;
+	const expectedFramework = task.expect.scope?.framework ?? requestedFramework;
+	const expectedVersion = task.expect.scope?.version ?? requestedVersion;
+	const expectedLocale = task.expect.scope?.locale ?? requestedLocale;
+	const framework = expectedFramework ? normalizeAgentFramework(expectedFramework) : void 0;
+	const locale = expectedLocale ? normalizeAgentLocale(expectedLocale) : void 0;
+	const candidates = sources.map((source) => {
+		const page = findPageForSource(pagesByUrl, source.pageUrl || source.url);
+		const scope = page ? getPageScope(page) : {
+			framework: normalizeAgentScopeValues(source.framework).map(normalizeAgentFramework),
+			version: normalizeAgentScopeValues(source.version).map(normalizeAgentVersion),
+			locale: normalizeAgentScopeValues(source.locale).map(normalizeAgentLocale),
+			frameworkAmbiguous: false,
+			versionAmbiguous: false
+		};
+		return {
+			source: canonicalizeSource(source.url),
+			scope
+		};
+	});
+	const firstFrameworkMatchRank = framework ? candidates.findIndex((candidate) => candidate.scope.framework.includes(framework)) + 1 || null : null;
+	const firstVersionMatchRank = expectedVersion ? candidates.findIndex((candidate) => candidate.scope.version.some((version) => agentVersionConstraintMatches(expectedVersion, version))) + 1 || null : null;
+	const firstLocaleMatchRank = locale ? candidates.findIndex((candidate) => candidate.scope.locale.includes(locale)) + 1 || null : null;
+	const conflictingSources = candidates.filter((candidate) => framework && candidate.scope.framework.length > 0 && !candidate.scope.framework.includes(framework) || expectedVersion && candidate.scope.version.length > 0 && !candidate.scope.version.some((version) => agentVersionConstraintMatches(expectedVersion, version)) || locale && candidate.scope.locale.length > 0 && !candidate.scope.locale.includes(locale)).map((candidate) => candidate.source);
+	const ambiguousSources = candidates.filter((candidate) => candidate.scope.frameworkAmbiguous || candidate.scope.versionAmbiguous || Boolean(framework && candidate.scope.framework.length === 0) || Boolean(expectedVersion && candidate.scope.version.length === 0) || Boolean(locale && candidate.scope.locale.length === 0)).map((candidate) => candidate.source);
+	return {
+		requestedFramework,
+		requestedVersion,
+		requestedLocale,
+		expectedFramework,
+		expectedVersion,
+		expectedLocale,
+		firstFrameworkMatchRank,
+		firstVersionMatchRank,
+		firstLocaleMatchRank,
+		conflictingSources,
+		ambiguousSources,
+		passed: (!framework || firstFrameworkMatchRank !== null) && (!expectedVersion || firstVersionMatchRank !== null) && (!locale || firstLocaleMatchRank !== null) && conflictingSources.length === 0 && ambiguousSources.length === 0
+	};
+}
+function buildUsageMetrics(task, tokenBudget, context, relevantSources, attributionUtf8Bytes, baseUrl) {
+	const usedUtf8Bytes = context.budget.usedUtf8Bytes;
+	const rendered = extractRenderedCitations(context.context, context.sources);
+	const blockUtf8Bytes = attributionUtf8Bytes ?? (rendered.layoutIntegrity ? rendered.blockUtf8Bytes : []);
+	const usefulUtf8Bytes = context.sources.reduce((total, source, index) => relevantSources.some((expected) => sourceMatches(source.url, expected, baseUrl)) ? total + (blockUtf8Bytes[index] ?? 0) : total, 0);
+	const usefulByteRatio = usedUtf8Bytes > 0 ? usefulUtf8Bytes / usedUtf8Bytes : 0;
+	const minimumUsefulRatio = clamp(task.expect.minUsefulByteRatio ?? 0, 0, 1);
+	const withinBudget = usedUtf8Bytes <= tokenBudget;
+	return {
+		budgetUnit: "utf8-bytes",
+		tokenBudget,
+		usedUtf8Bytes,
+		remainingUtf8Bytes: context.budget.remainingUtf8Bytes,
+		estimatedTokens: Math.ceil(usedUtf8Bytes / 4),
+		conservativeTokenUpperBound: usedUtf8Bytes,
+		usefulUtf8Bytes,
+		usefulByteRatio: round(usefulByteRatio),
+		truncated: context.budget.truncated,
+		withinBudget,
+		passed: withinBudget && usefulByteRatio >= minimumUsefulRatio
+	};
+}
+function calculateTaskScore(report) {
+	const dimensions = [
+		{
+			weight: 30,
+			score: report.retrieval.forbiddenSources.length > 0 ? 0 : (report.retrieval.recallAtK + report.retrieval.reciprocalRank) / 2
+		},
+		{
+			weight: 25,
+			score: report.citations.integrity ? (report.citations.precision + report.citations.recall) / 2 : 0
+		},
+		...report.hasSelectionExpectation ? [{
+			weight: 20,
+			score: report.selection.passed ? 1 : 0
+		}] : [],
+		...report.hasAnswerExpectation ? [{
+			weight: 25,
+			score: report.answer.passed ? 1 : 0
+		}] : [],
+		...report.hasExampleExpectation ? [{
+			weight: 15,
+			score: report.examples.expected > 0 ? report.examples.matched / report.examples.expected : 1
+		}] : [],
+		{
+			weight: 10,
+			score: report.usage.passed ? 1 : 0
+		}
+	];
+	const totalWeight = dimensions.reduce((sum, dimension) => sum + dimension.weight, 0);
+	return round(dimensions.reduce((sum, dimension) => sum + dimension.weight * dimension.score, 0) / totalWeight * 100);
+}
+async function evaluateTask(pages, task, configurationIssues = [], runOptions = {}) {
+	const topK = normalizePositiveInteger(task.topK, DEFAULT_TOP_K, 50);
+	const tokenBudget = normalizePositiveInteger(task.tokenBudget, DEFAULT_TOKEN_BUDGET, 1e6);
+	const relevantSources = uniqueCanonicalSources(task.expect.relevantSources, runOptions.baseUrl);
+	const orderedPages = pages.slice().sort((left, right) => compareCodePoints(canonicalizeSource(left.url), canonicalizeSource(right.url)));
+	const pagesByUrl = new Map(orderedPages.map((page) => [sourcePage(page.url), page]));
+	const requestedSurface = task.surface ?? runOptions.surface ?? "mcp-context";
+	let surfaceResult;
+	let surfaceError;
+	if (configurationIssues.length > 0) {
+		const empty = createContextShell({
+			query: task.query,
+			filters: task.filters,
+			tokenBudget
+		});
+		surfaceResult = {
+			surface: requestedSurface === "configured-search" || requestedSurface === "ask-ai-context" ? requestedSurface : "mcp-context",
+			provider: "unavailable",
+			rankedContext: empty,
+			budgetedContext: empty,
+			citationEvidence: {
+				mode: "context",
+				actual: [],
+				integrity: false
+			}
+		};
+	} else try {
+		if (requestedSurface !== "mcp-context" && requestedSurface !== "configured-search" && requestedSurface !== "ask-ai-context") throw new Error(`Unknown evaluation surface: ${String(requestedSurface)}.`);
+		surfaceResult = await buildGoldenSurface({
+			pages: orderedPages,
+			task,
+			topK,
+			tokenBudget,
+			runOptions
+		});
+	} catch (error) {
+		surfaceError = error instanceof Error ? error.message : String(error);
+		const empty = createContextShell({
+			query: task.query,
+			filters: task.filters,
+			tokenBudget
+		});
+		surfaceResult = {
+			surface: requestedSurface === "configured-search" || requestedSurface === "ask-ai-context" ? requestedSurface : "mcp-context",
+			provider: "unavailable",
+			rankedContext: empty,
+			budgetedContext: empty,
+			citationEvidence: {
+				mode: "context",
+				actual: [],
+				integrity: false
+			}
+		};
+	}
+	const { rankedContext, budgetedContext } = surfaceResult;
+	const rankedSources = toGoldenSources(rankedContext.sources, relevantSources, runOptions.baseUrl);
+	const budgetedSources = toGoldenSources(budgetedContext.sources, relevantSources, runOptions.baseUrl);
+	const budgetedCandidates = toContextCandidates(budgetedContext.sources, pagesByUrl);
+	const retrieval = buildRetrievalMetrics(task, rankedSources, topK, runOptions.baseUrl);
+	const citationSources = surfaceResult.citationEvidence.mode === "results" ? rankedContext.sources : budgetedContext.sources;
+	const citations = buildCitationMetrics(task, budgetedContext.context, citationSources, surfaceResult.citationEvidence, runOptions.baseUrl);
+	const selection = buildSelectionMetrics(task, rankedContext.sources, pagesByUrl);
+	const examples = await evaluateExamples(task.expect.examples ?? [], budgetedCandidates, runOptions);
+	const usage = buildUsageMetrics(task, tokenBudget, budgetedContext, relevantSources, surfaceResult.attributionUtf8Bytes, runOptions.baseUrl);
+	const issues = configurationIssues.map((issue) => `Invalid golden task configuration: ${issue}`);
+	if (surfaceError) issues.push(`Evaluation surface failed: ${surfaceError}`);
+	let answerResult;
+	let answerError;
+	if (configurationIssues.length === 0 && !surfaceError && task.expect.answer && runOptions.answer) try {
+		answerResult = await runAnswerProvider({
+			provider: runOptions.answer,
+			allowNetwork: runOptions.allowNetwork === true,
+			input: {
+				task: {
+					id: task.id,
+					query: task.query,
+					filters: task.filters
+				},
+				surface: surfaceResult.surface,
+				context: budgetedContext.context,
+				sources: budgetedContext.sources.map((source) => ({
+					url: source.url,
+					title: source.title,
+					framework: source.framework,
+					version: source.version,
+					locale: source.locale
+				}))
+			}
+		});
+	} catch (error) {
+		answerError = error instanceof Error ? error.message : String(error);
+		issues.push(`Answer evaluation failed: ${answerError}`);
+	}
+	const answer = buildAnswerMetrics(task, answerResult, runOptions.baseUrl);
+	if (relevantSources.length === 0) issues.push("No relevantSources are configured for this task.");
+	if (!retrieval.passed) issues.push("Retrieval did not satisfy the expected recall, rank, or exclusion rules.");
+	if (!citations.passed) issues.push(`${citations.evidence === "results" ? "Search-result" : "Context"} citations are missing, unexpected, or do not match source records.`);
+	if (task.expect.answer && !runOptions.answer) issues.push("Answer expectations require agent.evaluations.answer to be configured.");
+	if (!answer.passed) issues.push("The actual answer is missing required text/citations or contains invalid evidence.");
+	if (!selection.passed) issues.push("Retrieved sources are ambiguous or do not explicitly match the expected framework/version/locale.");
+	if (!examples.passed) issues.push("One or more expected examples did not meet the requested verification level.");
+	if (!usage.passed) issues.push("Context exceeded its budget or did not meet the configured useful-byte ratio.");
+	const passed = configurationIssues.length === 0 && !surfaceError && !answerError && relevantSources.length > 0 && retrieval.passed && citations.passed && answer.passed && selection.passed && examples.passed && usage.passed;
+	const calculatedScore = configurationIssues.length > 0 ? 0 : calculateTaskScore({
+		retrieval,
+		citations,
+		answer,
+		selection,
+		examples,
+		usage,
+		hasSelectionExpectation: Boolean(task.expect.scope?.framework || task.expect.scope?.version || task.expect.scope?.locale || task.filters?.framework || task.filters?.version || task.filters?.locale),
+		hasExampleExpectation: (task.expect.examples?.length ?? 0) > 0,
+		hasAnswerExpectation: Boolean(task.expect.answer)
+	});
+	const score = passed ? calculatedScore : Math.min(calculatedScore, 99);
+	return {
+		id: task.id,
+		query: task.query,
+		surface: surfaceResult.surface,
+		provider: surfaceResult.provider,
+		status: passed ? "passed" : "failed",
+		passed,
+		score,
+		context: budgetedContext.context,
+		sources: budgetedSources,
+		retrieval,
+		citations,
+		answer,
+		selection,
+		examples,
+		usage,
+		issues
+	};
+}
+/**
+* Run offline-by-default golden-task evaluations against MCP-ready docs pages.
+* Configured external retrieval, HTTP answers, and runtime execution require explicit opt-in.
+* An empty task list is intentionally unmeasured so CI cannot turn absent coverage into a pass.
+*/
+async function runDocsGoldenTasks(pages, tasks, options = {}) {
+	const runtimeTasks = tasks;
+	if (runtimeTasks === void 0 || Array.isArray(runtimeTasks) && runtimeTasks.length === 0) return {
+		status: "unmeasured",
+		passed: null,
+		score: null,
+		taskCount: 0,
+		passedTaskCount: 0,
+		failedTaskCount: 0,
+		tasks: []
+	};
+	const normalizedTasks = Array.isArray(runtimeTasks) ? runtimeTasks.map((task, index) => normalizeGoldenTaskInput(task, index)) : [normalizeGoldenTaskInput(runtimeTasks, 0, ["agent.evaluations.tasks must be an array."])];
+	const idCounts = normalizedTasks.reduce((counts, input) => {
+		counts.set(input.task.id, (counts.get(input.task.id) ?? 0) + 1);
+		return counts;
+	}, /* @__PURE__ */ new Map());
+	for (const input of normalizedTasks) if ((idCounts.get(input.task.id) ?? 0) > 1) input.issues.push(`task id ${JSON.stringify(input.task.id)} is duplicated.`);
+	const reports = await Promise.all(normalizedTasks.map(({ task, issues }) => evaluateTask(pages, task, issues, options)));
+	const passedTaskCount = reports.filter((task) => task.passed).length;
+	const failedTaskCount = reports.length - passedTaskCount;
+	return {
+		status: failedTaskCount === 0 ? "passed" : "failed",
+		passed: failedTaskCount === 0,
+		score: round(reports.reduce((sum, task) => sum + task.score, 0) / reports.length),
+		taskCount: reports.length,
+		passedTaskCount,
+		failedTaskCount,
+		tasks: reports
+	};
+}
+
+//#endregion
+export { buildDocsReviewWorkflowPathFilters as a, resolveDocsReviewConfig as c, buildDocsReviewWorkflow as i, DEFAULT_DOCS_REVIEW_SCORE_THRESHOLD as n, ensureDocsReviewWorkflow as o, DEFAULT_DOCS_REVIEW_WORKFLOW_PATH as r, readDocsReviewConfigFromSource as s, runDocsGoldenTasks as t };