@farming-labs/docs 0.2.120 → 0.2.121

package/dist/agent-feedback-evaluations.d.mts

@@ -0,0 +1,91 @@
+import { DocsAgentGoldenTask } from "./types.mjs";
+import { DocsAgentFeedbackImprovementReport } from "./agent-feedback-loop.mjs";
+import { DocsGoldenTasksReport } from "./agent-evals.mjs";
+
+//#region src/agent-feedback-evaluations.d.ts
+declare const DOCS_AGENT_FEEDBACK_EVALUATION_CANDIDATES_FORMAT: "farming-labs-agent-feedback-evaluation-candidates.v1";
+declare const DOCS_AGENT_FEEDBACK_EVALUATION_BASELINE_FORMAT: "farming-labs-agent-feedback-evaluation-baseline.v1";
+declare const DOCS_AGENT_FEEDBACK_EVALUATION_REGRESSION_FORMAT: "farming-labs-agent-feedback-evaluation-regression.v1";
+interface DocsAgentFeedbackEvaluationCandidate {
+  id: string;
+  fingerprint: string;
+  state: "candidate";
+  task: DocsAgentGoldenTask;
+  evidence: {
+    clusterId: string;
+    page: string;
+    occurrences: number;
+    outcomes: string[];
+  };
+  sanitization: {
+    redactionCount: number;
+  };
+  promotion: {
+    target: "agent.evaluations.tasks";
+    requiresHumanReview: true;
+  };
+}
+interface DocsAgentFeedbackEvaluationDuplicate {
+  clusterId: string;
+  taskId: string;
+  fingerprint: string;
+  reason: "existing-id" | "existing-fingerprint" | "duplicate-candidate";
+}
+interface DocsAgentFeedbackEvaluationCandidateRegistry {
+  format: typeof DOCS_AGENT_FEEDBACK_EVALUATION_CANDIDATES_FORMAT;
+  generatedAt: string;
+  sourceFeedbackCount: number;
+  sourceClusterCount: number;
+  candidateCount: number;
+  duplicateCount: number;
+  redactionCount: number;
+  candidates: DocsAgentFeedbackEvaluationCandidate[];
+  duplicates: DocsAgentFeedbackEvaluationDuplicate[];
+  promotion: {
+    mode: "review-required";
+    automaticallyUpdatesConfig: false;
+    automaticallyPublishes: false;
+  };
+}
+interface BuildDocsAgentFeedbackEvaluationCandidatesOptions {
+  generatedAt?: string;
+  existingTasks?: readonly DocsAgentGoldenTask[];
+}
+interface DocsAgentFeedbackEvaluationTaskBaseline {
+  id: string;
+  passed: boolean;
+  score: number;
+}
+interface DocsAgentFeedbackEvaluationBaseline {
+  format: typeof DOCS_AGENT_FEEDBACK_EVALUATION_BASELINE_FORMAT;
+  generatedAt: string;
+  score: number;
+  taskCount: number;
+  passedTaskCount: number;
+  tasks: DocsAgentFeedbackEvaluationTaskBaseline[];
+}
+interface DocsAgentFeedbackEvaluationRegression {
+  kind: "missing-task" | "new-failure" | "pass-to-fail" | "score-drop" | "suite-score-drop";
+  taskId?: string;
+  message: string;
+}
+interface DocsAgentFeedbackEvaluationRegressionReport {
+  format: typeof DOCS_AGENT_FEEDBACK_EVALUATION_REGRESSION_FORMAT;
+  passed: boolean;
+  baselineScore: number;
+  currentScore: number;
+  scoreDelta: number;
+  maxScoreDrop: number;
+  regressions: DocsAgentFeedbackEvaluationRegression[];
+}
+interface CompareDocsAgentFeedbackEvaluationOptions {
+  /** Maximum allowed score decrease for the suite and each task. @default 0 */
+  maxScoreDrop?: number;
+  /** Treat newly added failing tasks as regressions. @default true */
+  failOnNewFailures?: boolean;
+}
+declare function buildDocsAgentFeedbackEvaluationCandidates(report: DocsAgentFeedbackImprovementReport, options?: BuildDocsAgentFeedbackEvaluationCandidatesOptions): DocsAgentFeedbackEvaluationCandidateRegistry;
+declare function createDocsAgentFeedbackEvaluationBaseline(report: DocsGoldenTasksReport, generatedAt?: string): DocsAgentFeedbackEvaluationBaseline;
+declare function compareDocsAgentFeedbackEvaluationBaseline(current: DocsGoldenTasksReport, baseline: DocsAgentFeedbackEvaluationBaseline, options?: CompareDocsAgentFeedbackEvaluationOptions): DocsAgentFeedbackEvaluationRegressionReport;
+//#endregion
+export { BuildDocsAgentFeedbackEvaluationCandidatesOptions, CompareDocsAgentFeedbackEvaluationOptions, DOCS_AGENT_FEEDBACK_EVALUATION_BASELINE_FORMAT, DOCS_AGENT_FEEDBACK_EVALUATION_CANDIDATES_FORMAT, DOCS_AGENT_FEEDBACK_EVALUATION_REGRESSION_FORMAT, DocsAgentFeedbackEvaluationBaseline, DocsAgentFeedbackEvaluationCandidate, DocsAgentFeedbackEvaluationCandidateRegistry, DocsAgentFeedbackEvaluationDuplicate, DocsAgentFeedbackEvaluationRegression, DocsAgentFeedbackEvaluationRegressionReport, DocsAgentFeedbackEvaluationTaskBaseline, buildDocsAgentFeedbackEvaluationCandidates, compareDocsAgentFeedbackEvaluationBaseline, createDocsAgentFeedbackEvaluationBaseline };

package/dist/{agent-feedback-evaluations-CcMGlgsO.mjs → agent-feedback-evaluations.mjs}

@@ -1,4 +1,4 @@
-import { i as sha256DocsContent } from "./retrieval-digest-CT-eIEcp.mjs";
+import { sha256DocsContent } from "./retrieval-digest.mjs";
 
 //#region src/agent-feedback-evaluations.ts
 const DOCS_AGENT_FEEDBACK_EVALUATION_CANDIDATES_FORMAT = "farming-labs-agent-feedback-evaluation-candidates.v1";
@@ -237,4 +237,4 @@ function compareDocsAgentFeedbackEvaluationBaseline(current, baseline, options =
 }
 
 //#endregion
-export { compareDocsAgentFeedbackEvaluationBaseline as a, buildDocsAgentFeedbackEvaluationCandidates as i, DOCS_AGENT_FEEDBACK_EVALUATION_CANDIDATES_FORMAT as n, createDocsAgentFeedbackEvaluationBaseline as o, DOCS_AGENT_FEEDBACK_EVALUATION_REGRESSION_FORMAT as r, DOCS_AGENT_FEEDBACK_EVALUATION_BASELINE_FORMAT as t };
+export { DOCS_AGENT_FEEDBACK_EVALUATION_BASELINE_FORMAT, DOCS_AGENT_FEEDBACK_EVALUATION_CANDIDATES_FORMAT, DOCS_AGENT_FEEDBACK_EVALUATION_REGRESSION_FORMAT, buildDocsAgentFeedbackEvaluationCandidates, compareDocsAgentFeedbackEvaluationBaseline, createDocsAgentFeedbackEvaluationBaseline };

package/dist/agent-feedback-loop.d.mts

@@ -0,0 +1,45 @@
+import { DocsAgentFeedbackData, DocsAgentGoldenTask } from "./types.mjs";
+
+//#region src/agent-feedback-loop.d.ts
+declare const DOCS_AGENT_FEEDBACK_IMPROVEMENT_FORMAT: "farming-labs-agent-feedback-improvements.v1";
+interface DocsAgentFeedbackImprovementOptions {
+  /** Minimum failed reports required before a cluster becomes recurring. @default 2 */
+  minOccurrences?: number;
+  /** Stable report timestamp override for tests and reproducible automation. */
+  generatedAt?: string;
+}
+interface DocsAgentFeedbackIssueDraft {
+  title: string;
+  body: string;
+  labels: string[];
+}
+interface DocsAgentFeedbackCluster {
+  id: string;
+  page: string;
+  task: string;
+  occurrences: number;
+  outcomes: string[];
+  missingContext: string[];
+  docIssues: string[];
+  suggestedImprovements: string[];
+  goldenTask?: DocsAgentGoldenTask;
+  issue: DocsAgentFeedbackIssueDraft;
+}
+interface DocsAgentFeedbackImprovementReport {
+  format: typeof DOCS_AGENT_FEEDBACK_IMPROVEMENT_FORMAT;
+  generatedAt: string;
+  feedbackCount: number;
+  failureCount: number;
+  recurringClusterCount: number;
+  clusters: DocsAgentFeedbackCluster[];
+  goldenTasks: DocsAgentGoldenTask[];
+  issueDrafts: DocsAgentFeedbackIssueDraft[];
+  pullRequestDraft: {
+    title: string;
+    body: string;
+  };
+}
+declare function analyzeDocsAgentFeedback(feedback: readonly DocsAgentFeedbackData[], options?: DocsAgentFeedbackImprovementOptions): DocsAgentFeedbackImprovementReport;
+declare function readDocsAgentFeedbackFile(filePath: string): DocsAgentFeedbackData[];
+//#endregion
+export { DOCS_AGENT_FEEDBACK_IMPROVEMENT_FORMAT, DocsAgentFeedbackCluster, DocsAgentFeedbackImprovementOptions, DocsAgentFeedbackImprovementReport, DocsAgentFeedbackIssueDraft, analyzeDocsAgentFeedback, readDocsAgentFeedbackFile };

package/dist/{agent-feedback-loop-CcZL_sb1.mjs → agent-feedback-loop.mjs}

@@ -193,4 +193,4 @@ function readDocsAgentFeedbackFile(filePath) {
 }
 
 //#endregion
-export { analyzeDocsAgentFeedback as n, readDocsAgentFeedbackFile as r, DOCS_AGENT_FEEDBACK_IMPROVEMENT_FORMAT as t };
+export { DOCS_AGENT_FEEDBACK_IMPROVEMENT_FORMAT, analyzeDocsAgentFeedback, readDocsAgentFeedbackFile };

package/dist/agent-maintenance.d.mts

@@ -0,0 +1,71 @@
+import { DocsAgentGoldenTask } from "./types.mjs";
+
+//#region src/agent-maintenance.d.ts
+declare const DOCS_AGENT_MAINTENANCE_PROPOSAL_FORMAT: "farming-labs-agent-maintenance-proposals.v1";
+type DocsAgentMaintenanceSignalSource = "agent-feedback" | "ask-ai" | "git" | "issue" | "mcp" | "search" | "support";
+type DocsAgentMaintenanceSeverity = "info" | "warning" | "error" | "critical";
+interface DocsAgentMaintenanceSignal {
+  source: DocsAgentMaintenanceSignalSource;
+  /** Untrusted evidence summary. It is never interpreted as an instruction. */
+  summary: string;
+  /** Stable grouping key shared across signal sources. Defaults to task or summary. */
+  topic?: string;
+  page?: string;
+  task?: string;
+  severity?: DocsAgentMaintenanceSeverity;
+  /** Aggregated occurrence count represented by this signal. @default 1 */
+  count?: number;
+}
+interface DocsAgentMaintenanceIssueDraft {
+  title: string;
+  body: string;
+  labels: string[];
+}
+interface DocsAgentMaintenanceProposal {
+  id: string;
+  page: string;
+  topic: string;
+  task?: string;
+  impactScore: number;
+  occurrenceCount: number;
+  severity: DocsAgentMaintenanceSeverity;
+  sources: DocsAgentMaintenanceSignalSource[];
+  evidence: Array<{
+    source: DocsAgentMaintenanceSignalSource;
+    summary: string;
+    count: number;
+  }>;
+  recommendedActions: string[];
+  acceptanceCriteria: string[];
+  goldenTask?: DocsAgentGoldenTask;
+  issueDraft: DocsAgentMaintenanceIssueDraft;
+}
+interface DocsAgentMaintenanceProposalReport {
+  format: typeof DOCS_AGENT_MAINTENANCE_PROPOSAL_FORMAT;
+  generatedAt: string;
+  signalCount: number;
+  representedOccurrences: number;
+  proposalCount: number;
+  proposals: DocsAgentMaintenanceProposal[];
+  goldenTasks: DocsAgentGoldenTask[];
+  issueDrafts: DocsAgentMaintenanceIssueDraft[];
+  pullRequestDraft: {
+    title: string;
+    body: string;
+  };
+  execution: {
+    mode: "draft-only";
+    writesDocumentation: false;
+    publishesChanges: false;
+    requiresHumanReview: true;
+  };
+}
+interface AnalyzeDocsAgentMaintenanceSignalsOptions {
+  /** Minimum represented occurrences required before a proposal is emitted. @default 2 */
+  minOccurrences?: number;
+  generatedAt?: string;
+}
+declare function analyzeDocsAgentMaintenanceSignals(signals: readonly DocsAgentMaintenanceSignal[], options?: AnalyzeDocsAgentMaintenanceSignalsOptions): DocsAgentMaintenanceProposalReport;
+declare function parseDocsAgentMaintenanceSignals(content: string): DocsAgentMaintenanceSignal[];
+//#endregion
+export { AnalyzeDocsAgentMaintenanceSignalsOptions, DOCS_AGENT_MAINTENANCE_PROPOSAL_FORMAT, DocsAgentMaintenanceIssueDraft, DocsAgentMaintenanceProposal, DocsAgentMaintenanceProposalReport, DocsAgentMaintenanceSeverity, DocsAgentMaintenanceSignal, DocsAgentMaintenanceSignalSource, analyzeDocsAgentMaintenanceSignals, parseDocsAgentMaintenanceSignals };

package/dist/{agent-maintenance-CuZ7iAKq.mjs → agent-maintenance.mjs}

@@ -286,4 +286,4 @@ function parseDocsAgentMaintenanceSignals(content) {
 }
 
 //#endregion
-export { analyzeDocsAgentMaintenanceSignals as n, parseDocsAgentMaintenanceSignals as r, DOCS_AGENT_MAINTENANCE_PROPOSAL_FORMAT as t };
+export { DOCS_AGENT_MAINTENANCE_PROPOSAL_FORMAT, analyzeDocsAgentMaintenanceSignals, parseDocsAgentMaintenanceSignals };

package/dist/agent-provenance.d.mts

@@ -0,0 +1,23 @@
+//#region src/agent-provenance.d.ts
+declare const GENERATED_AGENT_PROVENANCE_MARKER = "@farming-labs/docs:generated";
+declare const GENERATED_AGENT_PROVENANCE_VERSION = 1;
+type GeneratedAgentSourceKind = "resolved-page" | "agent-md";
+interface GeneratedAgentProvenance {
+  version: number;
+  sourceKind: GeneratedAgentSourceKind;
+  sourceHash: string;
+  settingsHash: string;
+  outputHash: string;
+  generatedAt: string;
+}
+interface ParsedGeneratedAgentDocument {
+  provenance?: GeneratedAgentProvenance;
+  content: string;
+}
+declare function normalizeGeneratedAgentContent(value: string): string;
+declare function hashGeneratedAgentContent(value: string): string;
+declare function parseGeneratedAgentDocument(raw: string): ParsedGeneratedAgentDocument;
+declare function stripGeneratedAgentProvenance(raw: string): string;
+declare function serializeGeneratedAgentDocument(content: string, provenance: GeneratedAgentProvenance): string;
+//#endregion
+export { GENERATED_AGENT_PROVENANCE_MARKER, GENERATED_AGENT_PROVENANCE_VERSION, GeneratedAgentProvenance, GeneratedAgentSourceKind, hashGeneratedAgentContent, normalizeGeneratedAgentContent, parseGeneratedAgentDocument, serializeGeneratedAgentDocument, stripGeneratedAgentProvenance };

package/dist/agent-provenance.mjs

@@ -0,0 +1,77 @@
+//#region src/agent-provenance.ts
+const GENERATED_AGENT_PROVENANCE_MARKER = "@farming-labs/docs:generated";
+const GENERATED_AGENT_PROVENANCE_VERSION = 1;
+function normalizeLineEndings(value) {
+	return value.replace(/\r\n?/g, "\n").replace(/^\uFEFF/, "");
+}
+function normalizeGeneratedAgentContent(value) {
+	return normalizeLineEndings(value).trimEnd();
+}
+function hashGeneratedAgentContent(value) {
+	const normalized = normalizeGeneratedAgentContent(value);
+	const bytes = new TextEncoder().encode(normalized);
+	let hash = 14695981039346656037n;
+	for (const byte of bytes) {
+		hash ^= BigInt(byte);
+		hash = BigInt.asUintN(64, hash * 1099511628211n);
+	}
+	return `fnv1a64:${hash.toString(16).padStart(16, "0")}`;
+}
+function parseProvenanceBlock(rawBlock) {
+	const entries = /* @__PURE__ */ new Map();
+	for (const line of rawBlock.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		const separatorIndex = trimmed.indexOf("=");
+		if (separatorIndex <= 0) continue;
+		const key = trimmed.slice(0, separatorIndex).trim();
+		const value = trimmed.slice(separatorIndex + 1).trim();
+		if (!key || !value) continue;
+		entries.set(key, value);
+	}
+	const version = Number.parseInt(entries.get("version") ?? "", 10);
+	const sourceKind = entries.get("sourceKind");
+	const sourceHash = entries.get("sourceHash");
+	const settingsHash = entries.get("settingsHash");
+	const outputHash = entries.get("outputHash");
+	const generatedAt = entries.get("generatedAt");
+	if (!Number.isFinite(version) || sourceKind !== "resolved-page" && sourceKind !== "agent-md" || !sourceHash || !settingsHash || !outputHash || !generatedAt) return;
+	return {
+		version,
+		sourceKind,
+		sourceHash,
+		settingsHash,
+		outputHash,
+		generatedAt
+	};
+}
+function parseGeneratedAgentDocument(raw) {
+	const normalized = normalizeLineEndings(raw);
+	const headerPattern = new RegExp(`^<!-- ${GENERATED_AGENT_PROVENANCE_MARKER}\\n([\\s\\S]*?)\\n-->\\n?`);
+	const match = normalized.match(headerPattern);
+	if (!match) return { content: normalized };
+	return {
+		provenance: parseProvenanceBlock(match[1]),
+		content: normalized.slice(match[0].length)
+	};
+}
+function stripGeneratedAgentProvenance(raw) {
+	return parseGeneratedAgentDocument(raw).content;
+}
+function serializeGeneratedAgentDocument(content, provenance) {
+	const normalizedContent = normalizeGeneratedAgentContent(content);
+	return `${[
+		`<!-- ${GENERATED_AGENT_PROVENANCE_MARKER}`,
+		`version=${provenance.version}`,
+		`sourceKind=${provenance.sourceKind}`,
+		`sourceHash=${provenance.sourceHash}`,
+		`settingsHash=${provenance.settingsHash}`,
+		`outputHash=${provenance.outputHash}`,
+		`generatedAt=${provenance.generatedAt}`,
+		"-->",
+		normalizedContent
+	].join("\n")}\n`;
+}
+
+//#endregion
+export { GENERATED_AGENT_PROVENANCE_MARKER, GENERATED_AGENT_PROVENANCE_VERSION, hashGeneratedAgentContent, normalizeGeneratedAgentContent, parseGeneratedAgentDocument, serializeGeneratedAgentDocument, stripGeneratedAgentProvenance };

package/dist/agent-scope.mjs

@@ -0,0 +1,321 @@
+//#region src/agent-scope.ts
+/** Normalize framework aliases used by page metadata, agent contracts, MCP, and evaluations. */
+function normalizeAgentFramework(value) {
+	const normalized = value.toLowerCase().replace(/[^a-z0-9]/gu, "");
+	if ([
+		"next",
+		"nextjs",
+		"nextjsapp",
+		"reactnext"
+	].includes(normalized)) return "nextjs";
+	if ([
+		"tanstack",
+		"tanstackstart",
+		"start"
+	].includes(normalized)) return "tanstackstart";
+	if (["svelte", "sveltekit"].includes(normalized)) return "sveltekit";
+	if (["nuxt", "nuxtjs"].includes(normalized)) return "nuxt";
+	return normalized;
+}
+function normalizeAgentLocale(value) {
+	return value.trim().toLowerCase().replace(/_/gu, "-");
+}
+function normalizeAgentVersion(value) {
+	return value.trim().toLowerCase().replace(/^v(?=\d)/u, "");
+}
+function normalizeAgentScopeValues(value) {
+	const values = Array.isArray(value) ? value : typeof value === "string" ? [value] : [];
+	return Array.from(new Set(values.map((item) => item.trim()).filter(Boolean)));
+}
+function compareVersions(left, right) {
+	for (let index = 0; index < 3; index += 1) if (left[index] !== right[index]) return left[index] > right[index] ? 1 : -1;
+	return 0;
+}
+function parseExactVersion(value) {
+	const match = normalizeAgentVersion(value).match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-[0-9a-z.-]+)?(?:\+[0-9a-z.-]+)?$/iu);
+	if (!match) return void 0;
+	return [
+		Number(match[1]),
+		Number(match[2] ?? 0),
+		Number(match[3] ?? 0)
+	];
+}
+function parseVersionOperand(value) {
+	const normalized = normalizeAgentVersion(value);
+	if (normalized === "*" || normalized === "x") return {
+		version: [
+			0,
+			0,
+			0
+		],
+		components: 0,
+		wildcard: true
+	};
+	const match = normalized.match(/^(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?$/iu);
+	if (!match) return void 0;
+	const raw = [
+		match[1],
+		match[2],
+		match[3]
+	];
+	const wildcardIndex = raw.findIndex((part, index) => index > 0 && (part?.toLowerCase() === "x" || part === "*"));
+	if (wildcardIndex >= 0 && raw.slice(wildcardIndex + 1).some((part) => part && part.toLowerCase() !== "x" && part !== "*")) return;
+	const components = wildcardIndex >= 0 ? wildcardIndex : raw.filter(Boolean).length;
+	return {
+		version: [
+			Number(raw[0]),
+			Number(raw[1] ?? 0) || 0,
+			Number(raw[2] ?? 0) || 0
+		],
+		components,
+		wildcard: wildcardIndex >= 0
+	};
+}
+function nextVersionBoundary(operand) {
+	const [major, minor] = operand.version;
+	if (operand.components <= 0) return void 0;
+	if (operand.components === 1) return [
+		major + 1,
+		0,
+		0
+	];
+	return [
+		major,
+		minor + 1,
+		0
+	];
+}
+function operandRange(operand) {
+	if (operand.components === 0) return {
+		minimumInclusive: true,
+		maximumInclusive: false
+	};
+	if (operand.components < 3 || operand.wildcard) return {
+		minimum: operand.version,
+		minimumInclusive: true,
+		maximum: nextVersionBoundary(operand),
+		maximumInclusive: false
+	};
+	return {
+		minimum: operand.version,
+		minimumInclusive: true,
+		maximum: operand.version,
+		maximumInclusive: true
+	};
+}
+function caretRange(operand) {
+	const [major, minor, patch] = operand.version;
+	let maximum;
+	if (major > 0) maximum = [
+		major + 1,
+		0,
+		0
+	];
+	else if (operand.components <= 1) maximum = [
+		1,
+		0,
+		0
+	];
+	else if (minor > 0 || operand.components === 2) maximum = [
+		0,
+		minor + 1,
+		0
+	];
+	else maximum = [
+		0,
+		0,
+		patch + 1
+	];
+	return {
+		minimum: operand.version,
+		minimumInclusive: true,
+		maximum,
+		maximumInclusive: false
+	};
+}
+function tildeRange(operand) {
+	const [major, minor] = operand.version;
+	const maximum = operand.components <= 1 ? [
+		major + 1,
+		0,
+		0
+	] : [
+		major,
+		minor + 1,
+		0
+	];
+	return {
+		minimum: operand.version,
+		minimumInclusive: true,
+		maximum,
+		maximumInclusive: false
+	};
+}
+function intersectRanges(left, right) {
+	let minimum = left.minimum;
+	let minimumInclusive = left.minimumInclusive;
+	if (!minimum || right.minimum && compareVersions(right.minimum, minimum) > 0) {
+		minimum = right.minimum;
+		minimumInclusive = right.minimumInclusive;
+	} else if (right.minimum && compareVersions(right.minimum, minimum) === 0) minimumInclusive = minimumInclusive && right.minimumInclusive;
+	let maximum = left.maximum;
+	let maximumInclusive = left.maximumInclusive;
+	if (!maximum || right.maximum && compareVersions(right.maximum, maximum) < 0) {
+		maximum = right.maximum;
+		maximumInclusive = right.maximumInclusive;
+	} else if (right.maximum && compareVersions(right.maximum, maximum) === 0) maximumInclusive = maximumInclusive && right.maximumInclusive;
+	if (minimum && maximum) {
+		const compared = compareVersions(minimum, maximum);
+		if (compared > 0 || compared === 0 && !(minimumInclusive && maximumInclusive)) return void 0;
+	}
+	return {
+		minimum,
+		minimumInclusive,
+		maximum,
+		maximumInclusive
+	};
+}
+function comparatorRange(operator, operand) {
+	if (!operator || operator === "=") return operandRange(operand);
+	if (operator === ">=") return {
+		minimum: operand.version,
+		minimumInclusive: true,
+		maximumInclusive: false
+	};
+	if (operator === ">") {
+		const partialBoundary = operand.components < 3 ? nextVersionBoundary(operand) : void 0;
+		return {
+			minimum: partialBoundary ?? operand.version,
+			minimumInclusive: Boolean(partialBoundary),
+			maximumInclusive: false
+		};
+	}
+	if (operator === "<") return {
+		minimumInclusive: true,
+		maximum: operand.version,
+		maximumInclusive: false
+	};
+	const partialBoundary = operand.components < 3 ? nextVersionBoundary(operand) : void 0;
+	return {
+		minimumInclusive: true,
+		maximum: partialBoundary ?? operand.version,
+		maximumInclusive: !partialBoundary
+	};
+}
+function parseVersionRangeBranch(value) {
+	const branch = normalizeAgentVersion(value).trim();
+	if (!branch) return void 0;
+	const hyphen = branch.match(/^(.+?)\s+-\s+(.+)$/u);
+	if (hyphen) {
+		const minimumOperand = parseVersionOperand(hyphen[1]);
+		const maximumOperand = parseVersionOperand(hyphen[2]);
+		if (!minimumOperand || !maximumOperand) return void 0;
+		const maximumBoundary = maximumOperand.components < 3 ? nextVersionBoundary(maximumOperand) : maximumOperand.version;
+		return intersectRanges({
+			minimum: minimumOperand.version,
+			minimumInclusive: true,
+			maximumInclusive: false
+		}, {
+			minimumInclusive: true,
+			maximum: maximumBoundary,
+			maximumInclusive: maximumOperand.components === 3
+		});
+	}
+	const special = branch.match(/^(\^|~)\s*(.+)$/u);
+	if (special) {
+		const operand = parseVersionOperand(special[2]);
+		if (!operand || operand.components === 0) return void 0;
+		return special[1] === "^" ? caretRange(operand) : tildeRange(operand);
+	}
+	const comparators = Array.from(branch.matchAll(/(>=|<=|>|<|=)\s*([^\s]+)/gu));
+	if (comparators.length > 0) {
+		if (comparators.map((match) => match[0]).join(" ").replace(/\s+/gu, " ") !== branch.replace(/\s+/gu, " ")) return void 0;
+		let range = {
+			minimumInclusive: true,
+			maximumInclusive: false
+		};
+		for (const comparator of comparators) {
+			const operand = parseVersionOperand(comparator[2]);
+			if (!operand) return void 0;
+			const next = intersectRanges(range, comparatorRange(comparator[1], operand));
+			if (!next) return void 0;
+			range = next;
+		}
+		return range;
+	}
+	const operand = parseVersionOperand(branch);
+	return operand ? operandRange(operand) : void 0;
+}
+function parseVersionRanges(value) {
+	return normalizeAgentVersion(value).split("||").map((branch) => parseVersionRangeBranch(branch)).filter((range) => Boolean(range));
+}
+function parseVersionConstraintBranches(value) {
+	const ranges = parseVersionRanges(value);
+	if (ranges.length > 0) return ranges.map((range) => ({
+		kind: "range",
+		range
+	}));
+	const normalized = normalizeAgentVersion(value);
+	return normalized ? [{
+		kind: "opaque",
+		value: normalized
+	}] : [];
+}
+function intersectVersionConstraintBranches(left, right) {
+	if (left.kind === "opaque" || right.kind === "opaque") return left.kind === "opaque" && right.kind === "opaque" && left.value === right.value ? left : void 0;
+	const range = intersectRanges(left.range, right.range);
+	return range ? {
+		kind: "range",
+		range
+	} : void 0;
+}
+/**
+* Return true when choosing one alternative from every group can select one shared version.
+*
+* Each inner group is an OR list while the groups themselves are intersected. Computing the
+* accumulated range prevents pairwise matches from accepting three mutually incompatible scopes.
+*/
+function agentVersionConstraintGroupsOverlap(groups) {
+	if (groups.length === 0) return false;
+	let intersections = groups[0].flatMap(parseVersionConstraintBranches);
+	if (intersections.length === 0) return false;
+	for (const group of groups.slice(1)) {
+		const branches = group.flatMap(parseVersionConstraintBranches);
+		if (branches.length === 0) return false;
+		intersections = intersections.flatMap((intersection) => branches.map((branch) => intersectVersionConstraintBranches(intersection, branch)).filter((value) => Boolean(value)));
+		if (intersections.length === 0) return false;
+	}
+	return true;
+}
+function rangeContains(range, version) {
+	if (range.minimum) {
+		const compared = compareVersions(version, range.minimum);
+		if (compared < 0 || compared === 0 && !range.minimumInclusive) return false;
+	}
+	if (range.maximum) {
+		const compared = compareVersions(version, range.maximum);
+		if (compared > 0 || compared === 0 && !range.maximumInclusive) return false;
+	}
+	return true;
+}
+function rangesOverlap(left, right) {
+	return Boolean(intersectRanges(left, right));
+}
+/** Match an exact requested version against an exact or range-like documented constraint. */
+function agentVersionConstraintMatches(requested, constraint) {
+	if (normalizeAgentVersion(requested) === normalizeAgentVersion(constraint)) return Boolean(normalizeAgentVersion(requested));
+	const wanted = parseExactVersion(requested);
+	if (!wanted) return false;
+	return parseVersionRanges(constraint).some((range) => rangeContains(range, wanted));
+}
+/** Return true when two exact or range-like documented version constraints can select one version. */
+function agentVersionConstraintsOverlap(left, right) {
+	const normalizedLeft = normalizeAgentVersion(left);
+	if (normalizedLeft === normalizeAgentVersion(right)) return Boolean(normalizedLeft);
+	const leftRanges = parseVersionRanges(left);
+	const rightRanges = parseVersionRanges(right);
+	return leftRanges.some((leftRange) => rightRanges.some((rightRange) => rangesOverlap(leftRange, rightRange)));
+}
+
+//#endregion
+export { agentVersionConstraintGroupsOverlap, agentVersionConstraintMatches, agentVersionConstraintsOverlap, normalizeAgentFramework, normalizeAgentLocale, normalizeAgentScopeValues, normalizeAgentVersion };