@farming-labs/docs 0.2.119 → 0.2.121

package/dist/{markdown-sections-9Oxr33b-.mjs → markdown-sections.mjs}

@@ -1,707 +1,16 @@
+import { PAGE_AGENT_CONTRACT_END_MARKER, PAGE_AGENT_CONTRACT_START_MARKER } from "./agent-contract.mjs";
+import { createDocsMarkdownSectionCache } from "./markdown-section-cache.mjs";
 import { createProcessor } from "@mdx-js/mdx";
 import { slug } from "github-slugger";
 import { parseEntities } from "parse-entities";
 import remarkGfm from "remark-gfm";
 
-//#region src/access.ts
-function isRecord$1(value) {
-	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-function normalizeStrings(value) {
-	if (!Array.isArray(value)) return void 0;
-	const strings = Array.from(new Set(value.flatMap((item) => typeof item === "string" && item.trim() ? [item.trim()] : [])));
-	return strings.length > 0 ? strings : void 0;
-}
-function normalizeClaimValue(value) {
-	if (typeof value === "string") return value.trim() || void 0;
-	if (typeof value === "number" && Number.isFinite(value)) return value;
-	if (typeof value === "boolean") return value;
-	return normalizeStrings(value);
-}
-function normalizeDocsPageAccessPolicy(value) {
-	if (!isRecord$1(value)) return void 0;
-	const visibility = value.visibility === "public" || value.visibility === "authenticated" ? value.visibility : void 0;
-	const scopes = normalizeStrings(value.scopes);
-	const rawClaims = isRecord$1(value.claims) ? value.claims : void 0;
-	const claims = rawClaims ? Object.fromEntries(Object.entries(rawClaims).flatMap(([name, rawValue]) => {
-		const normalizedName = name.trim();
-		const normalizedValue = normalizeClaimValue(rawValue);
-		return normalizedName && normalizedValue !== void 0 ? [[normalizedName, normalizedValue]] : [];
-	})) : void 0;
-	const normalizedClaims = claims && Object.keys(claims).length > 0 ? claims : void 0;
-	if (!visibility && !scopes && !normalizedClaims) return void 0;
-	return {
-		...visibility ? { visibility } : {},
-		...scopes ? { scopes } : {},
-		...normalizedClaims ? { claims: normalizedClaims } : {}
-	};
-}
-function claimMatches(expected, actual) {
-	const expectedValues = Array.isArray(expected) ? expected : [expected];
-	const actualValues = Array.isArray(actual) ? actual : [actual];
-	return expectedValues.some((expectedValue) => actualValues.some((actualValue) => actualValue === expectedValue));
-}
-function isDocsPageAccessAllowed(policy, principal) {
-	if (!policy) return true;
-	if (!(policy.visibility !== "public" || Boolean(policy.scopes?.length) || Boolean(policy.claims && Object.keys(policy.claims).length > 0))) return true;
-	if (!principal) return false;
-	const scopes = new Set(principal.scopes ?? []);
-	if (policy.scopes?.some((scope) => !scopes.has(scope))) return false;
-	for (const [name, expected] of Object.entries(policy.claims ?? {})) if (!claimMatches(expected, principal.claims?.[name])) return false;
-	return true;
-}
-function isDocsAgentPageAccessible(page, principal) {
-	return isDocsPageAccessAllowed(page.agent?.access, principal);
-}
-function filterDocsPagesByAccess(pages, principal) {
-	return pages.filter((page) => isDocsAgentPageAccessible(page, principal));
-}
-
-//#endregion
-//#region src/agent-contract.ts
-const PAGE_AGENT_STRUCTURED_CONTRACT_FIELDS = [
-	"task",
-	"outcome",
-	"appliesTo",
-	"prerequisites",
-	"files",
-	"commands",
-	"sideEffects",
-	"verification",
-	"rollback",
-	"failureModes"
-];
-const PAGE_AGENT_CONTRACT_FIELDS = [
-	"tokenBudget",
-	"access",
-	...PAGE_AGENT_STRUCTURED_CONTRACT_FIELDS
-];
-const PAGE_AGENT_CONTRACT_FIELD_SCHEMA = {
-	tokenBudget: "number",
-	access: "{visibility?,scopes?,claims?}",
-	task: "string",
-	outcome: "string",
-	appliesTo: {
-		framework: "string|string[]",
-		version: "string|string[]",
-		package: "string|string[]"
-	},
-	prerequisites: "string[]",
-	files: "string[]",
-	commands: "Array<string|{run,cwd?,description?}>",
-	sideEffects: "string[]",
-	verification: "Array<string|{description?,run?,expect?}>",
-	rollback: "string[]",
-	failureModes: "Array<string|{symptom,resolution?}>"
-};
-const APPLIES_TO_FIELDS = [
-	"framework",
-	"version",
-	"package"
-];
-const COMMAND_FIELDS = [
-	"run",
-	"cwd",
-	"description"
-];
-const VERIFICATION_FIELDS = [
-	"description",
-	"run",
-	"expect"
-];
-const FAILURE_MODE_FIELDS = ["symptom", "resolution"];
-const ACCESS_FIELDS = [
-	"visibility",
-	"scopes",
-	"claims"
-];
-const PAGE_AGENT_CONTRACT_START_MARKER = "<!-- farming-labs:agent-contract:start -->";
-const PAGE_AGENT_CONTRACT_END_MARKER = "<!-- farming-labs:agent-contract:end -->";
-function isRecord(value) {
-	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-function normalizeString(value) {
-	if (typeof value !== "string") return void 0;
-	return value.trim() || void 0;
-}
-function normalizeStringList(value) {
-	if (!Array.isArray(value)) return void 0;
-	const seen = /* @__PURE__ */ new Set();
-	const normalized = [];
-	for (const item of value) {
-		const text = normalizeString(item);
-		if (!text || seen.has(text)) continue;
-		seen.add(text);
-		normalized.push(text);
-	}
-	return normalized.length > 0 ? normalized : void 0;
-}
-function normalizeStringOrList(value) {
-	const single = normalizeString(value);
-	if (single) return [single];
-	return normalizeStringList(value);
-}
-function normalizeAppliesTo(value) {
-	if (!isRecord(value)) return void 0;
-	const framework = normalizeStringOrList(value.framework);
-	const version = normalizeStringOrList(value.version);
-	const packageNames = normalizeStringOrList(value.package);
-	if (!framework && !version && !packageNames) return void 0;
-	return {
-		...framework ? { framework } : {},
-		...version ? { version } : {},
-		...packageNames ? { package: packageNames } : {}
-	};
-}
-function normalizeCommands(value) {
-	if (!Array.isArray(value)) return void 0;
-	const commands = [];
-	for (const item of value) {
-		const shorthand = normalizeString(item);
-		if (shorthand) {
-			commands.push(shorthand);
-			continue;
-		}
-		if (!isRecord(item)) continue;
-		const run = normalizeString(item.run);
-		if (!run) continue;
-		const cwd = normalizeString(item.cwd);
-		const description = normalizeString(item.description);
-		commands.push({
-			run,
-			...cwd ? { cwd } : {},
-			...description ? { description } : {}
-		});
-	}
-	return commands.length > 0 ? commands : void 0;
-}
-function normalizeVerification(value) {
-	if (!Array.isArray(value)) return void 0;
-	const verification = [];
-	for (const item of value) {
-		const shorthand = normalizeString(item);
-		if (shorthand) {
-			verification.push(shorthand);
-			continue;
-		}
-		if (!isRecord(item)) continue;
-		const description = normalizeString(item.description);
-		const run = normalizeString(item.run);
-		const expect = normalizeString(item.expect);
-		if (!description && !run && !expect) continue;
-		verification.push({
-			...description ? { description } : {},
-			...run ? { run } : {},
-			...expect ? { expect } : {}
-		});
-	}
-	return verification.length > 0 ? verification : void 0;
-}
-function normalizeFailureModes(value) {
-	if (!Array.isArray(value)) return void 0;
-	const failureModes = [];
-	for (const item of value) {
-		const shorthand = normalizeString(item);
-		if (shorthand) {
-			failureModes.push(shorthand);
-			continue;
-		}
-		if (!isRecord(item)) continue;
-		const symptom = normalizeString(item.symptom);
-		if (!symptom) continue;
-		const resolution = normalizeString(item.resolution);
-		failureModes.push({
-			symptom,
-			...resolution ? { resolution } : {}
-		});
-	}
-	return failureModes.length > 0 ? failureModes : void 0;
-}
-function normalizeTokenBudget(value) {
-	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return void 0;
-	return Math.ceil(value);
-}
-/**
-* Normalize untrusted page frontmatter into the stable agent contract shape.
-* Invalid fields are omitted so malformed author input cannot break page delivery.
-*/
-function normalizePageAgentFrontmatter(value) {
-	if (!isRecord(value)) return void 0;
-	const tokenBudget = normalizeTokenBudget(value.tokenBudget);
-	const access = "access" in value ? normalizeDocsPageAccessPolicy(value.access) ?? { visibility: "authenticated" } : void 0;
-	const task = normalizeString(value.task);
-	const outcome = normalizeString(value.outcome);
-	const appliesTo = normalizeAppliesTo(value.appliesTo);
-	const prerequisites = normalizeStringList(value.prerequisites);
-	const files = normalizeStringList(value.files);
-	const commands = normalizeCommands(value.commands);
-	const sideEffects = normalizeStringList(value.sideEffects);
-	const verification = normalizeVerification(value.verification);
-	const rollback = normalizeStringList(value.rollback);
-	const failureModes = normalizeFailureModes(value.failureModes);
-	const normalized = {
-		...tokenBudget !== void 0 ? { tokenBudget } : {},
-		...access ? { access } : {},
-		...task ? { task } : {},
-		...outcome ? { outcome } : {},
-		...appliesTo ? { appliesTo } : {},
-		...prerequisites ? { prerequisites } : {},
-		...files ? { files } : {},
-		...commands ? { commands } : {},
-		...sideEffects ? { sideEffects } : {},
-		...verification ? { verification } : {},
-		...rollback ? { rollback } : {},
-		...failureModes ? { failureModes } : {}
-	};
-	return Object.keys(normalized).length > 0 ? normalized : void 0;
-}
-function hasStructuredPageAgentContract(value) {
-	const normalized = normalizePageAgentFrontmatter(value);
-	if (!normalized) return false;
-	return PAGE_AGENT_STRUCTURED_CONTRACT_FIELDS.some((field) => normalized[field] !== void 0);
-}
-function addStringIssue(issues, object, field) {
-	if (!(field in object)) return;
-	if (!normalizeString(object[field])) issues.push({
-		path: `agent.${field}`,
-		message: "must be a non-empty string"
-	});
-}
-function addStringListIssues(issues, object, field) {
-	if (!(field in object)) return;
-	const value = object[field];
-	if (!Array.isArray(value) || value.length === 0) {
-		issues.push({
-			path: `agent.${field}`,
-			message: "must be a non-empty string array"
-		});
-		return;
-	}
-	value.forEach((item, index) => {
-		if (!normalizeString(item)) issues.push({
-			path: `agent.${field}[${index}]`,
-			message: "must be a non-empty string"
-		});
-	});
-}
-function editDistance(left, right) {
-	const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
-	for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
-		const current = [leftIndex];
-		for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) current[rightIndex] = Math.min((current[rightIndex - 1] ?? 0) + 1, (previous[rightIndex] ?? 0) + 1, (previous[rightIndex - 1] ?? 0) + (left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1));
-		previous.splice(0, previous.length, ...current);
-	}
-	return previous[right.length] ?? 0;
-}
-function closestKnownField(field, allowed) {
-	const closest = allowed.map((candidate) => ({
-		candidate,
-		distance: editDistance(field, candidate)
-	})).sort((left, right) => left.distance - right.distance || left.candidate.localeCompare(right.candidate))[0];
-	if (!closest) return void 0;
-	const threshold = Math.max(1, Math.min(3, Math.floor(closest.candidate.length / 3)));
-	return closest.distance <= threshold ? closest.candidate : void 0;
-}
-function addUnknownKeyIssues(issues, object, allowed, path) {
-	for (const field of Object.keys(object)) {
-		if (allowed.includes(field)) continue;
-		const suggestion = closestKnownField(field, allowed);
-		issues.push({
-			path: `${path}.${field}`,
-			message: suggestion ? `is not recognized; did you mean "${path}.${suggestion}"?` : "is not recognized"
-		});
-	}
-}
-/** Return author-facing validation issues without throwing. */
-function getPageAgentFrontmatterIssues(value) {
-	if (value === void 0) return [];
-	if (!isRecord(value)) return [{
-		path: "agent",
-		message: "must be an object"
-	}];
-	const issues = [];
-	addUnknownKeyIssues(issues, value, PAGE_AGENT_CONTRACT_FIELDS, "agent");
-	if ("tokenBudget" in value && (typeof value.tokenBudget !== "number" || !Number.isFinite(value.tokenBudget) || value.tokenBudget <= 0)) issues.push({
-		path: "agent.tokenBudget",
-		message: "must be a positive finite number"
-	});
-	if ("access" in value) if (!isRecord(value.access)) issues.push({
-		path: "agent.access",
-		message: "must be an object"
-	});
-	else {
-		addUnknownKeyIssues(issues, value.access, ACCESS_FIELDS, "agent.access");
-		if ("visibility" in value.access && value.access.visibility !== "public" && value.access.visibility !== "authenticated") issues.push({
-			path: "agent.access.visibility",
-			message: "must be \"public\" or \"authenticated\""
-		});
-		if ("scopes" in value.access && !normalizeStringList(value.access.scopes)) issues.push({
-			path: "agent.access.scopes",
-			message: "must be a non-empty string array"
-		});
-		if ("claims" in value.access) {
-			if (!isRecord(value.access.claims) || Object.keys(value.access.claims).length === 0) issues.push({
-				path: "agent.access.claims",
-				message: "must be a non-empty object"
-			});
-			else for (const [name, claim] of Object.entries(value.access.claims)) if (!name.trim() || normalizeDocsPageAccessPolicy({ claims: { [name]: claim } }) === void 0) issues.push({
-				path: `agent.access.claims.${name || "<empty>"}`,
-				message: "must be a string, number, boolean, or non-empty string array"
-			});
-		}
-		if (!normalizeDocsPageAccessPolicy(value.access)) issues.push({
-			path: "agent.access",
-			message: "must include a valid visibility, scope, or claim"
-		});
-	}
-	addStringIssue(issues, value, "task");
-	addStringIssue(issues, value, "outcome");
-	if ("appliesTo" in value) if (!isRecord(value.appliesTo)) issues.push({
-		path: "agent.appliesTo",
-		message: "must be an object"
-	});
-	else {
-		addUnknownKeyIssues(issues, value.appliesTo, APPLIES_TO_FIELDS, "agent.appliesTo");
-		for (const field of [
-			"framework",
-			"version",
-			"package"
-		]) {
-			if (!(field in value.appliesTo)) continue;
-			const fieldValue = value.appliesTo[field];
-			if (!normalizeStringOrList(fieldValue)) {
-				issues.push({
-					path: `agent.appliesTo.${field}`,
-					message: "must be a non-empty string or string array"
-				});
-				continue;
-			}
-			if (Array.isArray(fieldValue)) fieldValue.forEach((item, index) => {
-				if (!normalizeString(item)) issues.push({
-					path: `agent.appliesTo.${field}[${index}]`,
-					message: "must be a non-empty string"
-				});
-			});
-		}
-		if (!normalizeAppliesTo(value.appliesTo)) issues.push({
-			path: "agent.appliesTo",
-			message: "must include framework, version, or package"
-		});
-	}
-	for (const field of [
-		"prerequisites",
-		"files",
-		"sideEffects",
-		"rollback"
-	]) addStringListIssues(issues, value, field);
-	if ("commands" in value) if (!Array.isArray(value.commands) || value.commands.length === 0) issues.push({
-		path: "agent.commands",
-		message: "must be a non-empty array"
-	});
-	else value.commands.forEach((command, index) => {
-		if (normalizeString(command)) return;
-		if (!isRecord(command)) {
-			issues.push({
-				path: `agent.commands[${index}]`,
-				message: "must be a command string or an object with a non-empty run field"
-			});
-			return;
-		}
-		addUnknownKeyIssues(issues, command, COMMAND_FIELDS, `agent.commands[${index}]`);
-		if (!normalizeString(command.run)) {
-			issues.push({
-				path: `agent.commands[${index}]`,
-				message: "must be a command string or an object with a non-empty run field"
-			});
-			return;
-		}
-		for (const field of ["cwd", "description"]) if (field in command && !normalizeString(command[field])) issues.push({
-			path: `agent.commands[${index}].${field}`,
-			message: "must be a non-empty string"
-		});
-	});
-	if ("verification" in value) if (!Array.isArray(value.verification) || value.verification.length === 0) issues.push({
-		path: "agent.verification",
-		message: "must be a non-empty array"
-	});
-	else value.verification.forEach((step, index) => {
-		if (normalizeString(step)) return;
-		if (!isRecord(step)) {
-			issues.push({
-				path: `agent.verification[${index}]`,
-				message: "must be a string or an object with description, run, or expect"
-			});
-			return;
-		}
-		addUnknownKeyIssues(issues, step, VERIFICATION_FIELDS, `agent.verification[${index}]`);
-		if (!normalizeVerification([step])) {
-			issues.push({
-				path: `agent.verification[${index}]`,
-				message: "must be a string or an object with description, run, or expect"
-			});
-			return;
-		}
-		for (const field of [
-			"description",
-			"run",
-			"expect"
-		]) if (field in step && !normalizeString(step[field])) issues.push({
-			path: `agent.verification[${index}].${field}`,
-			message: "must be a non-empty string"
-		});
-	});
-	if ("failureModes" in value) if (!Array.isArray(value.failureModes) || value.failureModes.length === 0) issues.push({
-		path: "agent.failureModes",
-		message: "must be a non-empty array"
-	});
-	else value.failureModes.forEach((mode, index) => {
-		if (normalizeString(mode)) return;
-		if (!isRecord(mode)) {
-			issues.push({
-				path: `agent.failureModes[${index}]`,
-				message: "must be a string or an object with a non-empty symptom field"
-			});
-			return;
-		}
-		addUnknownKeyIssues(issues, mode, FAILURE_MODE_FIELDS, `agent.failureModes[${index}]`);
-		if (!normalizeString(mode.symptom)) {
-			issues.push({
-				path: `agent.failureModes[${index}]`,
-				message: "must be a string or an object with a non-empty symptom field"
-			});
-			return;
-		}
-		if ("resolution" in mode && !normalizeString(mode.resolution)) issues.push({
-			path: `agent.failureModes[${index}].resolution`,
-			message: "must be a non-empty string"
-		});
-	});
-	return issues;
-}
-function yamlString(value) {
-	return JSON.stringify(value);
-}
-function renderYamlStringList(lines, indent, key, values) {
-	lines.push(`${indent}${key}:`);
-	for (const value of values) lines.push(`${indent}  - ${yamlString(value)}`);
-}
-function renderYamlObjectList(lines, indent, key, values, fields) {
-	lines.push(`${indent}${key}:`);
-	for (const value of values) {
-		if (typeof value === "string") {
-			lines.push(`${indent}  - ${yamlString(value)}`);
-			continue;
-		}
-		const record = value;
-		const firstField = fields.find((field) => normalizeString(record[field]));
-		if (!firstField) continue;
-		lines.push(`${indent}  - ${firstField}: ${yamlString(normalizeString(record[firstField]))}`);
-		for (const field of fields) {
-			const fieldValue = normalizeString(record[field]);
-			if (field === firstField || !fieldValue) continue;
-			lines.push(`${indent}    ${field}: ${yamlString(fieldValue)}`);
-		}
-	}
-}
-/** Render normalized `agent` YAML in a stable field order. */
-function renderPageAgentFrontmatterYamlLines(value, indentation = 0) {
-	const agent = normalizePageAgentFrontmatter(value);
-	if (!agent) return [];
-	const indent = " ".repeat(Math.max(0, indentation));
-	const child = `${indent}  `;
-	const lines = [`${indent}agent:`];
-	if (agent.tokenBudget !== void 0) lines.push(`${child}tokenBudget: ${agent.tokenBudget}`);
-	if (agent.access) {
-		lines.push(`${child}access:`);
-		const accessIndent = `${child}  `;
-		if (agent.access.visibility) lines.push(`${accessIndent}visibility: ${agent.access.visibility}`);
-		if (agent.access.scopes) renderYamlStringList(lines, accessIndent, "scopes", [...agent.access.scopes]);
-		if (agent.access.claims) {
-			lines.push(`${accessIndent}claims:`);
-			const claimsIndent = `${accessIndent}  `;
-			for (const [name, claim] of Object.entries(agent.access.claims).sort(([left], [right]) => left.localeCompare(right))) if (Array.isArray(claim)) renderYamlStringList(lines, claimsIndent, yamlString(name), [...claim]);
-			else lines.push(`${claimsIndent}${yamlString(name)}: ${typeof claim === "string" ? yamlString(claim) : claim}`);
-		}
-	}
-	if (agent.task) lines.push(`${child}task: ${yamlString(agent.task)}`);
-	if (agent.outcome) lines.push(`${child}outcome: ${yamlString(agent.outcome)}`);
-	if (agent.appliesTo) {
-		lines.push(`${child}appliesTo:`);
-		const appliesIndent = `${child}  `;
-		for (const field of [
-			"framework",
-			"version",
-			"package"
-		]) {
-			const values = normalizeStringOrList(agent.appliesTo[field]);
-			if (values) renderYamlStringList(lines, appliesIndent, field, values);
-		}
-	}
-	if (agent.prerequisites) renderYamlStringList(lines, child, "prerequisites", agent.prerequisites);
-	if (agent.files) renderYamlStringList(lines, child, "files", agent.files);
-	if (agent.commands) renderYamlObjectList(lines, child, "commands", agent.commands, [
-		"run",
-		"cwd",
-		"description"
-	]);
-	if (agent.sideEffects) renderYamlStringList(lines, child, "sideEffects", agent.sideEffects);
-	if (agent.verification) renderYamlObjectList(lines, child, "verification", agent.verification, [
-		"description",
-		"run",
-		"expect"
-	]);
-	if (agent.rollback) renderYamlStringList(lines, child, "rollback", agent.rollback);
-	if (agent.failureModes) renderYamlObjectList(lines, child, "failureModes", agent.failureModes, ["symptom", "resolution"]);
-	return lines;
-}
-function inlineCode(value) {
-	const longestRun = Math.max(0, ...[...value.matchAll(/`+/g)].map((match) => match[0].length));
-	const fence = "`".repeat(longestRun + 1);
-	const padding = value.startsWith("`") || value.endsWith("`") ? " " : "";
-	return `${fence}${padding}${value}${padding}${fence}`;
-}
-function renderTextList(lines, title, values, code = false) {
-	lines.push("", `### ${title}`, "");
-	for (const value of values) lines.push(`- ${code ? inlineCode(value) : value}`);
-}
-/** Render the structured contract as deterministic, compact machine-readable Markdown. */
-function renderPageAgentContractMarkdown(value) {
-	const agent = normalizePageAgentFrontmatter(value);
-	if (!agent || !hasStructuredPageAgentContract(agent)) return "";
-	const lines = [PAGE_AGENT_CONTRACT_START_MARKER, "## Agent Contract"];
-	if (agent.task) lines.push("", `Task: ${agent.task}`);
-	if (agent.outcome) lines.push(`Outcome: ${agent.outcome}`);
-	if (agent.appliesTo) {
-		lines.push("", "### Applies To", "");
-		for (const [label, field] of [
-			["Framework", "framework"],
-			["Version", "version"],
-			["Package", "package"]
-		]) {
-			const values = normalizeStringOrList(agent.appliesTo[field]);
-			if (values) lines.push(`- ${label}: ${values.map(inlineCode).join(", ")}`);
-		}
-	}
-	if (agent.prerequisites) renderTextList(lines, "Prerequisites", agent.prerequisites);
-	if (agent.files) renderTextList(lines, "Files", agent.files, true);
-	if (agent.commands) {
-		lines.push("", "### Commands", "");
-		for (const command of agent.commands) {
-			if (typeof command === "string") {
-				lines.push(`- ${inlineCode(command)}`);
-				continue;
-			}
-			const details = [command.cwd ? `cwd ${inlineCode(command.cwd)}` : void 0, command.description].filter(Boolean);
-			lines.push(`- ${inlineCode(command.run)}${details.length ? ` — ${details.join("; ")}` : ""}`);
-		}
-	}
-	if (agent.sideEffects) renderTextList(lines, "Side Effects", agent.sideEffects);
-	if (agent.verification) {
-		lines.push("", "### Verification", "");
-		for (const step of agent.verification) {
-			if (typeof step === "string") {
-				lines.push(`- ${step}`);
-				continue;
-			}
-			const summary = step.description ?? (step.run ? `Run ${inlineCode(step.run)}` : step.expect ?? "Verification step");
-			lines.push(`- ${summary}`);
-			if (step.run && step.description) lines.push(`  - Run: ${inlineCode(step.run)}`);
-			if (step.expect && step.expect !== summary) lines.push(`  - Expected: ${step.expect}`);
-		}
-	}
-	if (agent.rollback) renderTextList(lines, "Rollback", agent.rollback);
-	if (agent.failureModes) {
-		lines.push("", "### Failure Modes", "");
-		for (const mode of agent.failureModes) {
-			if (typeof mode === "string") {
-				lines.push(`- ${mode}`);
-				continue;
-			}
-			lines.push(`- ${mode.symptom}${mode.resolution ? ` — Recovery: ${mode.resolution}` : ""}`);
-		}
-	}
-	lines.push(PAGE_AGENT_CONTRACT_END_MARKER);
-	return lines.join("\n");
-}
-/** Remove generated contract blocks while preserving handwritten guidance. */
-function stripGeneratedPageAgentContractMarkdown(markdown) {
-	const newline = markdown.includes("\r\n") ? "\r\n" : "\n";
-	const output = [];
-	let fence;
-	let pendingBlock;
-	let skipEmptySeparator = false;
-	for (const line of markdown.split(/\r?\n/)) {
-		if (pendingBlock) {
-			pendingBlock.push(line);
-			if (isGeneratedAgentContractMarker(line, PAGE_AGENT_CONTRACT_END_MARKER)) {
-				pendingBlock = void 0;
-				skipEmptySeparator = true;
-			}
-			continue;
-		}
-		if (!fence && isGeneratedAgentContractMarker(line, PAGE_AGENT_CONTRACT_START_MARKER)) {
-			pendingBlock = [line];
-			continue;
-		}
-		if (skipEmptySeparator && line.length === 0) continue;
-		skipEmptySeparator = false;
-		output.push(line);
-		fence = advanceMarkdownFence(line, fence);
-	}
-	if (pendingBlock) output.push(...pendingBlock);
-	while (output[0] === "") output.shift();
-	return output.join(newline);
-}
-function isGeneratedAgentContractMarker(line, marker) {
-	if (line.trim() !== marker) return false;
-	const markerIndex = line.indexOf(marker);
-	return markerIndex <= 3 && /^ *$/.test(line.slice(0, markerIndex));
-}
-function advanceMarkdownFence(line, fence) {
-	if (fence) {
-		const closing = /^ {0,3}(`+|~+)[\t ]*$/.exec(line)?.[1];
-		if (closing?.[0] === fence.character && closing.length >= fence.length) return;
-		return fence;
-	}
-	const opening = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
-	if (!opening?.[1]) return void 0;
-	if (opening[1][0] === "`" && opening[2]?.includes("`")) return void 0;
-	return {
-		character: opening[1][0],
-		length: opening[1].length
-	};
-}
-function isAgentContractHeadingText(value) {
-	return value.trim().toLowerCase() === "agent contract";
-}
-function hasPageAgentContractHeading(markdown) {
-	let fence;
-	let previousLine;
-	for (const line of markdown.split(/\r?\n/)) {
-		const nextFence = advanceMarkdownFence(line, fence);
-		if (fence || nextFence) {
-			fence = nextFence;
-			previousLine = void 0;
-			continue;
-		}
-		const atxText = /^ {0,3}#{1,6}(?:[\t ]+|$)(.*)$/.exec(line)?.[1]?.replace(/[\t ]+#+[\t ]*$/, "").trim();
-		if (atxText && isAgentContractHeadingText(atxText)) return true;
-		if (previousLine && /^ {0,3}(?:=+|-+)[\t ]*$/.test(line) && isAgentContractHeadingText(previousLine)) return true;
-		previousLine = line.trim().length > 0 && !/^ {4}/.test(line) && !/^ {0,3}\t/.test(line) ? line : void 0;
-	}
-	return false;
-}
-/** Insert one generated contract unless the document already has handwritten contract guidance. */
-function upsertPageAgentContractMarkdown(markdown, value) {
-	const cleaned = stripGeneratedPageAgentContractMarkdown(markdown);
-	const contract = renderPageAgentContractMarkdown(value);
-	if (!contract || hasPageAgentContractHeading(cleaned)) return cleaned;
-	return cleaned ? `${contract}\n\n${cleaned.replace(/^\r?\n+/, "")}` : contract;
-}
-
-//#endregion
 //#region src/markdown-sections.ts
-const docsMarkdownMdxProcessor = createProcessor({ remarkPlugins: [remarkGfm] });
+let docsMarkdownMdxProcessor;
+const docsMarkdownSections = createDocsMarkdownSectionCache();
+function getDocsMarkdownMdxProcessor() {
+	return docsMarkdownMdxProcessor ??= createProcessor({ remarkPlugins: [remarkGfm] });
+}
 function isDocsMarkdownLiteralPrompt(node) {
 	return (node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement") && node.name === "Prompt";
 }
@@ -1440,6 +749,17 @@ function stripDocsGeneratedAgentContractMarkers(markdown, location) {
 function isDocsMarkdownLineInRanges(line, ranges) {
 	return ranges.some((range) => line >= range.start && line <= range.end);
 }
+/** Close each section at the next heading of the same or a shallower level. */
+function resolveDocsMarkdownSectionEnds(headings, lineCount) {
+	const ends = headings.map(() => lineCount);
+	const open = [];
+	for (let index = 0; index < headings.length; index += 1) {
+		const heading = headings[index];
+		while (open.length > 0 && headings[open[open.length - 1]].level >= heading.level) ends[open.pop()] = heading.start;
+		open.push(index);
+	}
+	return ends;
+}
 /**
 * Parse heading sections once for search, Ask AI hydration, and MCP tools.
 * Supports CommonMark ATX indentation, Setext headings, fenced-code exclusion,
@@ -1524,8 +844,9 @@ function parseDocsMarkdownSectionsFallback(markdown, generatedContractRanges) {
 	const resolveHeadingAnchor = createDocsMarkdownHeadingAnchorResolverWithReferences(definedReferences);
 	const orderedHeadings = [...headings.filter((heading) => !isDocsMarkdownLineInRanges(heading.start, generatedContractRanges)), ...headings.filter((heading) => isDocsMarkdownLineInRanges(heading.start, generatedContractRanges))];
 	for (const heading of orderedHeadings) heading.resolved = resolveHeadingAnchor(heading.source);
+	const ends = resolveDocsMarkdownSectionEnds(headings, lines.length);
 	return headings.map((heading, index) => {
-		const end = headings.slice(index + 1).find((candidate) => candidate.level <= heading.level)?.start ?? lines.length;
+		const end = ends[index];
 		const resolved = heading.resolved;
 		if (!resolved) throw new Error("Failed to resolve a Markdown heading anchor.");
 		return {
@@ -1545,7 +866,7 @@ function stripDocsMarkdownSectionFrontmatter(markdown) {
 function parseDocsMarkdownAstSections(markdown, generatedContractRanges) {
 	let root;
 	try {
-		root = docsMarkdownMdxProcessor.parse(markdown);
+		root = getDocsMarkdownMdxProcessor().parse(markdown);
 	} catch {
 		return;
 	}
@@ -1562,8 +883,9 @@ function parseDocsMarkdownAstSections(markdown, generatedContractRanges) {
 		}];
 	});
 	const lines = markdown.split(/\r?\n/u);
+	const ends = resolveDocsMarkdownSectionEnds(headings, lines.length);
 	return headings.map((heading, index) => {
-		const end = headings.slice(index + 1).find((candidate) => candidate.level <= heading.level)?.start ?? lines.length;
+		const end = ends[index];
 		return {
 			title: heading.title,
 			anchor: heading.anchor,
@@ -1577,8 +899,12 @@ function parseDocsMarkdownAstSections(markdown, generatedContractRanges) {
 }
 function parseDocsMarkdownSections(markdown) {
 	const body = stripDocsMarkdownSectionFrontmatter(markdown);
+	const cached = docsMarkdownSections.get(body);
+	if (cached) return cached;
 	const generatedContractRanges = collectGeneratedAgentContractRanges(body);
-	return parseDocsMarkdownAstSections(body, generatedContractRanges) ?? parseDocsMarkdownSectionsFallback(body, generatedContractRanges);
+	const sections = parseDocsMarkdownAstSections(body, generatedContractRanges) ?? parseDocsMarkdownSectionsFallback(body, generatedContractRanges);
+	docsMarkdownSections.set(body, sections);
+	return sections;
 }
 function findDocsMarkdownSection(markdown, requestedSection) {
 	const sections = parseDocsMarkdownSections(markdown);
@@ -1597,4 +923,4 @@ function findDocsMarkdownSection(markdown, requestedSection) {
 }
 
 //#endregion
-export { filterDocsPagesByAccess as C, normalizeDocsPageAccessPolicy as E, upsertPageAgentContractMarkdown as S, isDocsPageAccessAllowed as T, hasStructuredPageAgentContract as _, findDocsGeneratedAgentContractRanges as a, renderPageAgentFrontmatterYamlLines as b, slugifyDocsMarkdownHeading as c, PAGE_AGENT_CONTRACT_END_MARKER as d, PAGE_AGENT_CONTRACT_FIELDS as f, getPageAgentFrontmatterIssues as g, PAGE_AGENT_STRUCTURED_CONTRACT_FIELDS as h, createDocsRenderedHeadingAnchorResolver as i, stripDocsGeneratedAgentContractMarkers as l, PAGE_AGENT_CONTRACT_START_MARKER as m, cleanDocsRenderedHeadingLabel as n, findDocsMarkdownSection as o, PAGE_AGENT_CONTRACT_FIELD_SCHEMA as p, createDocsMarkdownHeadingAnchorResolver as r, parseDocsMarkdownSections as s, applyDocsMarkdownHeadingAnchors as t, withDocsMarkdownRenderableHeadings as u, normalizePageAgentFrontmatter as v, isDocsAgentPageAccessible as w, stripGeneratedPageAgentContractMarkdown as x, renderPageAgentContractMarkdown as y };
+export { applyDocsMarkdownHeadingAnchors, cleanDocsRenderedHeadingLabel, createDocsMarkdownHeadingAnchorResolver, createDocsRenderedHeadingAnchorResolver, findDocsGeneratedAgentContractRanges, findDocsMarkdownSection, parseDocsMarkdownSections, slugifyDocsMarkdownHeading, stripDocsGeneratedAgentContractMarkers, withDocsMarkdownRenderableHeadings };