@iowarp/clio-coder 0.3.8 → 0.3.9

package/src/domains/evidence/build.ts

@@ -24,6 +24,7 @@ import {
 	type SessionEntry,
 } from "../session/index.js";
 import { attributeEvidenceFailure } from "./failure-attribution.js";
+import { renderEvidenceFindingsMarkdown } from "./findings-markdown.js";
 import { compareCodepoints as compareStrings } from "./ordering.js";
 import { extractRunProvenance, provenanceTranscriptLines } from "./provenance.js";
 import { createRedactionTally, redactSecretsDeep, redactSecretsText } from "./redact.js";
@@ -159,7 +160,6 @@ export async function buildEvidence(options: BuildEvidenceOptions): Promise<Evid
 		evidenceId,
 		runSources,
 		gateDecisions: gateDecisions.decisions,
-		auditRows: auditLinks.rows,
 		validationEvidence,
 	});
 	const findings = buildFindings(runSources, trustStatusRaw, sessionLinks, auditLinks, protectedArtifactsRaw);
@@ -630,7 +630,7 @@ async function writeEvidenceFiles(
 	await writeJson(join(directory, "trust-status.json"), trustStatus);
 	await writeJson(join(directory, "protected-artifacts.json"), protectedArtifacts);
 	await writeJson(join(directory, "findings.json"), findingsFile(overview.evidenceId, [...findings]));
-	await writeFile(join(directory, "findings.md"), renderFindings(findings), "utf8");
+	await writeFile(join(directory, "findings.md"), renderEvidenceFindingsMarkdown(findings, trustStatus), "utf8");
 }
 
 function rawTraceRows(runSources: ReadonlyArray<EvidenceRunSource>): EvidenceRawTraceRow[] {
@@ -1493,17 +1493,6 @@ function axisFindings(offset: number, source: EvidenceRunSource, status: Canonic
 	return out;
 }
 
-function renderFindings(findings: ReadonlyArray<EvidenceFinding>): string {
-	if (findings.length === 0) return "# Findings\n\nNo findings.\n";
-	const lines = ["# Findings", ""];
-	for (const item of findings) {
-		const run = item.runId === null ? "" : ` run=${item.runId}`;
-		lines.push(`- ${item.id} [${item.severity}] ${item.tag}${run}: ${item.message}`);
-	}
-	lines.push("");
-	return `${lines.join("\n")}\n`;
-}
-
 async function readRunLedger(stateDir: string): Promise<RunLedgerRows> {
 	const target = join(stateDir, "runs.json");
 	let raw: string;

package/src/domains/evidence/eval.ts

@@ -5,6 +5,7 @@ import { readGateDecisionArtifactsForRunIds } from "../dispatch/index.js";
 import { redactArtifactForStorage } from "../eval/artifacts/redact.js";
 import type { EvalCommandResult, EvalRunArtifact, EvalRunRecord } from "../eval/index.js";
 import { loadEvalArtifact } from "../eval/index.js";
+import { renderEvidenceFindingsMarkdown } from "./findings-markdown.js";
 import { compareCodepoints as compareStrings } from "./ordering.js";
 import { buildEvidenceTrustStatusFile } from "./run-trust.js";
 import { evidenceDirectory, findingsFile } from "./store.js";
@@ -95,7 +96,6 @@ export async function buildEvalEvidence(options: BuildEvalEvidenceOptions): Prom
 		evidenceId,
 		runSources: linkedRuns.runSources,
 		gateDecisions: gateDecisions.decisions,
-		auditRows: linkedRuns.auditRows,
 	});
 	await writeEvalEvidenceFiles(
 		directory,
@@ -258,7 +258,7 @@ async function writeEvalEvidenceFiles(
 	await writeJson(join(directory, "protected-artifacts.json"), emptyProtected);
 	await writeJson(join(directory, "eval-result.json"), redactedArtifact);
 	await writeJson(join(directory, "findings.json"), findingsFile(overview.evidenceId, [...findings]));
-	await writeFile(join(directory, "findings.md"), renderFindings(findings), "utf8");
+	await writeFile(join(directory, "findings.md"), renderEvidenceFindingsMarkdown(findings, trustStatus), "utf8");
 }
 
 function rawEvalTraceRows(artifact: EvalRunArtifact): EvidenceEvalRawTraceRow[] {
@@ -360,16 +360,6 @@ function renderEvalTranscript(artifact: EvalRunArtifact, overview: EvidenceOverv
 	return `${lines.join("\n")}\n`;
 }
 
-function renderFindings(findings: ReadonlyArray<EvidenceFinding>): string {
-	if (findings.length === 0) return "No findings.\n";
-	const lines = ["# Findings", ""];
-	for (const finding of findings) {
-		lines.push(`- ${finding.id} [${finding.severity}] ${finding.tag}: ${finding.message}`);
-	}
-	lines.push("");
-	return `${lines.join("\n")}\n`;
-}
-
 async function writeJson(path: string, value: unknown): Promise<void> {
 	await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
 }

package/src/domains/evidence/findings-markdown.ts

@@ -0,0 +1,33 @@
+import { formatTrustAxes, formatTrustSummary, trustVerdict } from "./trust-projection.js";
+import type { EvidenceFinding, EvidenceTrustStatusFile } from "./types.js";
+
+/** Render the canonical verdict before the diagnostic records in every evidence bundle. */
+export function renderEvidenceFindingsMarkdown(
+	findings: ReadonlyArray<EvidenceFinding>,
+	trustStatus: EvidenceTrustStatusFile,
+): string {
+	const lines = ["# Findings", "", "## Canonical trust", ""];
+	if (trustStatus.runs.length === 0) {
+		lines.push("No linked run trust status.");
+	} else {
+		for (const run of trustStatus.runs) {
+			lines.push(
+				`- run=${run.runId}`,
+				`  tier: ${trustVerdict(run.status)}`,
+				`  summary: ${formatTrustSummary(run.status)}`,
+				`  axes: ${formatTrustAxes(run.status)}`,
+			);
+		}
+	}
+	lines.push("", "## Finding records", "");
+	if (findings.length === 0) {
+		lines.push("No findings.");
+	} else {
+		for (const item of findings) {
+			const run = item.runId === null ? "" : ` run=${item.runId}`;
+			lines.push(`- ${item.id} [${item.severity}] ${item.tag}${run}: ${item.message}`);
+		}
+	}
+	lines.push("");
+	return `${lines.join("\n")}\n`;
+}

package/src/domains/evidence/run-trust.ts

@@ -1,9 +1,7 @@
 import { type GateDecisionArtifact, verifyGateDecisionArtifact } from "../dispatch/gate-decisions.js";
 import type { RunEnvelope, RunReceipt } from "../dispatch/types.js";
-import type { FinishContractAssessment, FinishContractEvidenceKind } from "../safety/finish-contract.js";
 import { compareCodepoints as compareStrings } from "./ordering.js";
 import {
-	adaptFinishContractCompletionStatus,
 	adaptGateDecisionReviewStatus,
 	adaptGroundedEvidenceValidationStatus,
 	type CanonicalTrustStatus,
@@ -12,7 +10,7 @@ import {
 	isTrustStatusIdentifier,
 	type TrustArtifactReference,
 } from "./trust-status.js";
-import { EVIDENCE_VERSION, type EvidenceAuditLinkedRow, type EvidenceTrustStatusFile } from "./types.js";
+import { EVIDENCE_VERSION, type EvidenceTrustStatusFile } from "./types.js";
 
 export interface EvidenceRunTrustSource {
 	envelope: RunEnvelope;
@@ -23,15 +21,15 @@ export interface BuildEvidenceTrustStatusInput {
 	evidenceId: string;
 	runSources: ReadonlyArray<EvidenceRunTrustSource>;
 	gateDecisions: ReadonlyArray<GateDecisionArtifact>;
-	auditRows: ReadonlyArray<EvidenceAuditLinkedRow>;
 	validationEvidence?: ReadonlyMap<string, ReadonlyArray<TrustArtifactReference>>;
 }
 
 /**
  * Compose every evidence-linked trust axis at one pure boundary. Both the
  * run/session and eval builders call this function, so the same authenticated
- * receipt, gate decision, and exact finish-contract row cannot project
- * differently merely because it was bundled through a different entry point.
+ * receipt and gate decision cannot project differently merely because the
+ * receipt was bundled through a different entry point. Completion evidence
+ * stays receipt-derived so an audit row cannot change one surface alone.
  */
 export function buildEvidenceTrustStatusFile(input: BuildEvidenceTrustStatusInput): EvidenceTrustStatusFile {
 	return {
@@ -44,7 +42,6 @@ export function buildEvidenceTrustStatusFile(input: BuildEvidenceTrustStatusInpu
 				evidenceId: input.evidenceId,
 				source,
 				gateDecisions: input.gateDecisions,
-				auditRows: input.auditRows,
 				validationEvidence: input.validationEvidence?.get(source.envelope.id) ?? [],
 			}),
 		})),
@@ -55,22 +52,15 @@ interface ComposeEvidenceRunTrustInput {
 	evidenceId: string;
 	source: EvidenceRunTrustSource;
 	gateDecisions: ReadonlyArray<GateDecisionArtifact>;
-	auditRows: ReadonlyArray<EvidenceAuditLinkedRow>;
 	validationEvidence: ReadonlyArray<TrustArtifactReference>;
 }
 
 function composeEvidenceRunTrustStatus(input: ComposeEvidenceRunTrustInput): CanonicalTrustStatus {
 	const inspection = inspectRunReceiptTrustStatus(input.source.receipt, input.source.envelope);
-	// A receipt that was presented and rejected authenticates nothing about the
-	// run it names. Its integrity failure stays on `artifactIntegrity`; no other
-	// axis may reach a trust-granting state on the strength of that run's own
-	// self-reports. A missing or unchecked receipt is not a rejection.
-	const receiptRejected = inspection.status.artifactIntegrity.state === "failed";
 	let status = inspection.status;
-	// Only independently observed executions ground validation. The
-	// completion-contract audit row is the run's own self-report: it feeds
-	// `completionEvidence` below and nothing else. The cross-axis rules this
-	// enforces are listed under "composition rules" in docs/evidence-and-memory.md.
+	// Only independently observed executions ground validation. A completion
+	// contract audit row is the run's own self-report and cannot override the
+	// receipt-derived completion axis on this surface alone.
 	const grounded = input.validationEvidence.filter((artifact) => isTrustStatusIdentifier(artifact.id));
 	if (
 		grounded.length > 0 &&
@@ -106,25 +96,6 @@ function composeEvidenceRunTrustStatus(input: ComposeEvidenceRunTrustInput): Can
 			independentReview: adaptGateDecisionReviewStatus(gate, input.source.envelope.id, verification),
 		});
 	}
-
-	const finish = latestFinishContractForRun(input.auditRows, input.source.envelope.id);
-	if (finish !== null) {
-		const completion = adaptFinishContractCompletionStatus(finish.assessment, {
-			sourceId: finish.sourceId,
-			artifacts: finish.artifacts,
-		});
-		status = composeTrustStatus(status, {
-			completionEvidence:
-				receiptRejected && completion.state === "evidenced"
-					? {
-							state: "unknown",
-							source: { kind: "finish_contract", id: finish.sourceId },
-							authority: { kind: "clio", id: "finish-contract" },
-							artifacts: finish.artifacts,
-						}
-					: completion,
-		});
-	}
 	return status;
 }
 
@@ -142,80 +113,3 @@ function latestGateDecisionForRun(
 			.at(-1) ?? null
 	);
 }
-
-interface EvidenceFinishContractProjection {
-	sourceId: string;
-	assessment: FinishContractAssessment;
-	artifacts: TrustArtifactReference[];
-}
-
-function latestFinishContractForRun(
-	rows: ReadonlyArray<EvidenceAuditLinkedRow>,
-	runId: string,
-): EvidenceFinishContractProjection | null {
-	const candidates = rows
-		.filter((row) => row.auditKind === "completion_contract" && row.runId === runId && row.confidence === "exact")
-		.flatMap((row) => {
-			const assessment = finishContractAssessmentFromAudit(row.row);
-			if (assessment === null) return [];
-			const correlationId = readOptionalString(row.row.correlationId) ?? `${runId}:completion-contract`;
-			// A malformed row is dropped from the trust projection rather than
-			// thrown out of the whole forensic build. `readAuditRows` already
-			// reports the malformed line, so the bundle stays honest about it.
-			if (!isTrustStatusIdentifier(correlationId)) return [];
-			const turnId = readOptionalString(row.row.turnId);
-			const artifacts: TrustArtifactReference[] = [
-				{ kind: "finish_contract_evidence", id: correlationId },
-				...(turnId === null || !isTrustStatusIdentifier(turnId) ? [] : [{ kind: "session_entry" as const, id: turnId }]),
-			];
-			return [{ sourceId: correlationId, assessment, artifacts, timestamp: row.ts ?? "" }];
-		})
-		.sort(
-			(left, right) => compareStrings(left.timestamp, right.timestamp) || compareStrings(left.sourceId, right.sourceId),
-		);
-	const latest = candidates.at(-1);
-	return latest === undefined
-		? null
-		: { sourceId: latest.sourceId, assessment: latest.assessment, artifacts: latest.artifacts };
-}
-
-function finishContractAssessmentFromAudit(row: Record<string, unknown>): FinishContractAssessment | null {
-	const reason = readOptionalString(row.reason);
-	const decision = readOptionalString(row.decision);
-	const mutatedPaths = Array.isArray(row.mutatedPaths)
-		? row.mutatedPaths.filter((entry): entry is string => typeof entry === "string")
-		: [];
-	const turnId = readOptionalString(row.turnId);
-	const evidenceKinds = Array.isArray(row.evidenceKinds) ? row.evidenceKinds.filter(isFinishContractEvidenceKind) : [];
-	const evidence = evidenceKinds.map((kind) => ({
-		kind,
-		summary: "recorded by the finish contract",
-		...(turnId === null ? {} : { turnId }),
-	}));
-	if (decision === "ok" && reason === "no_mutation") {
-		return { kind: "ok", reason, evidence: [], mutatedPaths };
-	}
-	if (decision === "ok" && reason === "validation_evidence") {
-		return { kind: "ok", reason, evidence, mutatedPaths };
-	}
-	if (decision === "ok" && reason === "explicit_limitation") {
-		return { kind: "ok", reason, evidence: [], mutatedPaths };
-	}
-	if (decision === "engage" && reason === "unvalidated_mutation") {
-		return { kind: "engage", reason, message: "finish contract engaged", evidence: [], mutatedPaths };
-	}
-	return null;
-}
-
-function isFinishContractEvidenceKind(value: unknown): value is FinishContractEvidenceKind {
-	return value === "validation_command" || value === "protected_artifact" || value === "dispatch_receipt";
-}
-
-/**
- * A blank or whitespace-only optional field is absent, not an identifier. The
- * `??` fallbacks below depend on it, and an empty string would otherwise reach
- * `normalizeArtifactReference` and abort the entire bundle.
- */
-function readOptionalString(value: unknown): string | null {
-	return typeof value === "string" && value.trim().length > 0 ? value : null;
-}

package/src/domains/evidence/trust-projection.ts

@@ -184,9 +184,9 @@ export function formatTrustSummary(status: CanonicalTrustStatus): string {
 	].join("; ");
 }
 
-/** The body under its versioned label, for surfaces that print one line per run. */
+/** The tier and body under one versioned label for receipt-facing surfaces. */
 export function formatTrustSummaryLine(status: CanonicalTrustStatus): string {
-	return `trust v${TRUST_SUMMARY_VERSION}: ${formatTrustSummary(status)}`;
+	return `trust v${TRUST_SUMMARY_VERSION}: ${trustVerdict(status)}; ${formatTrustSummary(status)}`;
 }
 
 /**

package/src/domains/extensions/compatibility.ts

@@ -0,0 +1,285 @@
+/**
+ * SemVer range evaluation for extension compatibility.
+ *
+ * Extension manifests are untrusted package input, so this parser is bounded
+ * and fail-closed. It accepts the ordinary npm range vocabulary authors use in
+ * manifests: comparator sets, `||`, exact and partial versions, wildcards,
+ * hyphen ranges, caret ranges, and tilde ranges. Tags and malformed or
+ * overlong expressions are rejected instead of being treated as compatible.
+ */
+
+import { getVersionInfo } from "../lifecycle/version.js";
+
+const MAX_RANGE_CHARS = 256;
+
+interface SemVer {
+	major: number;
+	minor: number;
+	patch: number;
+	prerelease: ReadonlyArray<string | number>;
+}
+
+interface PartialVersion {
+	major: number | null;
+	minor: number | null;
+	patch: number | null;
+	prerelease: ReadonlyArray<string | number>;
+}
+
+type Predicate = (version: SemVer) => boolean;
+
+const NUMERIC = "(?:0|[1-9]\\d*)";
+const IDENTIFIER = "[0-9A-Za-z-]+";
+const VERSION_RE = new RegExp(
+	`^v?(${NUMERIC})\\.(${NUMERIC})\\.(${NUMERIC})(?:-(${IDENTIFIER}(?:\\.${IDENTIFIER})*))?(?:\\+${IDENTIFIER}(?:\\.${IDENTIFIER})*)?$`,
+);
+const PARTIAL_RE = new RegExp(
+	`^v?(${NUMERIC}|[xX*])(?:\\.(${NUMERIC}|[xX*]))?(?:\\.(${NUMERIC}|[xX*]))?(?:-(${IDENTIFIER}(?:\\.${IDENTIFIER})*))?(?:\\+${IDENTIFIER}(?:\\.${IDENTIFIER})*)?$`,
+);
+
+function prerelease(value: string | undefined): ReadonlyArray<string | number> | null {
+	if (value === undefined) return [];
+	const out: Array<string | number> = [];
+	for (const identifier of value.split(".")) {
+		if (identifier.length === 0) return null;
+		if (/^\d+$/u.test(identifier)) {
+			if (identifier.length > 1 && identifier.startsWith("0")) return null;
+			const parsed = Number(identifier);
+			if (!Number.isSafeInteger(parsed)) return null;
+			out.push(parsed);
+		} else {
+			out.push(identifier);
+		}
+	}
+	return out;
+}
+
+function parseSemVer(value: string): SemVer | null {
+	const match = VERSION_RE.exec(value);
+	if (match === null) return null;
+	const parsedPrerelease = prerelease(match[4]);
+	if (parsedPrerelease === null) return null;
+	const major = Number(match[1]);
+	const minor = Number(match[2]);
+	const patch = Number(match[3]);
+	if (![major, minor, patch].every(Number.isSafeInteger)) return null;
+	return { major, minor, patch, prerelease: parsedPrerelease };
+}
+
+function parsePart(value: string | undefined): number | null {
+	if (value === undefined || value === "x" || value === "X" || value === "*") return null;
+	const parsed = Number(value);
+	return Number.isSafeInteger(parsed) ? parsed : null;
+}
+
+function parsePartial(value: string): PartialVersion | null {
+	const match = PARTIAL_RE.exec(value);
+	if (match === null) return null;
+	for (const part of match.slice(1, 4)) {
+		if (part === undefined || part === "x" || part === "X" || part === "*") continue;
+		if (!Number.isSafeInteger(Number(part))) return null;
+	}
+	const major = parsePart(match[1]);
+	const minor = parsePart(match[2]);
+	const patch = parsePart(match[3]);
+	// A wildcard closes the core. `1.x.3` is not a range with a coherent
+	// meaning, and accepting it differently from npm would be worse than a
+	// parse-time refusal.
+	if (
+		(major === null && (match[2] !== undefined || match[3] !== undefined)) ||
+		(minor === null && match[3] !== undefined)
+	) {
+		return null;
+	}
+	const parsedPrerelease = prerelease(match[4]);
+	if (parsedPrerelease === null) return null;
+	if (parsedPrerelease.length > 0 && (major === null || minor === null || patch === null)) return null;
+	return { major, minor, patch, prerelease: parsedPrerelease };
+}
+
+function compareIdentifiers(left: string | number, right: string | number): number {
+	if (left === right) return 0;
+	if (typeof left === "number" && typeof right === "number") return left < right ? -1 : 1;
+	if (typeof left === "number") return -1;
+	if (typeof right === "number") return 1;
+	return left < right ? -1 : 1;
+}
+
+function compare(left: SemVer, right: SemVer): number {
+	for (const key of ["major", "minor", "patch"] as const) {
+		if (left[key] !== right[key]) return left[key] < right[key] ? -1 : 1;
+	}
+	if (left.prerelease.length === 0 || right.prerelease.length === 0) {
+		if (left.prerelease.length === right.prerelease.length) return 0;
+		return left.prerelease.length === 0 ? 1 : -1;
+	}
+	const length = Math.max(left.prerelease.length, right.prerelease.length);
+	for (let index = 0; index < length; index += 1) {
+		const leftPart = left.prerelease[index];
+		const rightPart = right.prerelease[index];
+		if (leftPart === undefined || rightPart === undefined) {
+			if (leftPart === rightPart) return 0;
+			return leftPart === undefined ? -1 : 1;
+		}
+		const order = compareIdentifiers(leftPart, rightPart);
+		if (order !== 0) return order;
+	}
+	return 0;
+}
+
+function floor(partial: PartialVersion): SemVer {
+	return {
+		major: partial.major ?? 0,
+		minor: partial.minor ?? 0,
+		patch: partial.patch ?? 0,
+		prerelease: partial.prerelease,
+	};
+}
+
+function nextWildcard(partial: PartialVersion): SemVer | null {
+	if (partial.major === null) return null;
+	if (partial.minor === null) return { major: partial.major + 1, minor: 0, patch: 0, prerelease: [] };
+	if (partial.patch === null) return { major: partial.major, minor: partial.minor + 1, patch: 0, prerelease: [] };
+	return null;
+}
+
+function lowerBound(version: SemVer, inclusive: boolean): Predicate {
+	return (candidate) => (inclusive ? compare(candidate, version) >= 0 : compare(candidate, version) > 0);
+}
+
+function upperBound(version: SemVer, inclusive: boolean): Predicate {
+	return (candidate) => (inclusive ? compare(candidate, version) <= 0 : compare(candidate, version) < 0);
+}
+
+function core(version: SemVer): string {
+	return `${version.major}.${version.minor}.${version.patch}`;
+}
+
+function predicatesForToken(token: string): { predicates: Predicate[]; prereleaseCore: string | null } | null {
+	const match = /^(<=|>=|<|>|=|~|\^)?(.+)$/u.exec(token);
+	if (match === null) return null;
+	const operator = match[1] ?? "";
+	const partial = parsePartial(match[2] ?? "");
+	if (partial === null) return null;
+	const base = floor(partial);
+	const wildcardUpper = nextWildcard(partial);
+	const prereleaseCore = partial.prerelease.length > 0 ? core(base) : null;
+
+	if (operator === "" || operator === "=") {
+		if (partial.major === null) return { predicates: [], prereleaseCore };
+		if (wildcardUpper !== null) {
+			return { predicates: [lowerBound(base, true), upperBound(wildcardUpper, false)], prereleaseCore };
+		}
+		return { predicates: [(candidate) => compare(candidate, base) === 0], prereleaseCore };
+	}
+	if (operator === ">=") return { predicates: [lowerBound(base, true)], prereleaseCore };
+	if (operator === "<") return { predicates: [upperBound(base, false)], prereleaseCore };
+	if (operator === ">") {
+		return {
+			predicates: [wildcardUpper === null ? lowerBound(base, false) : lowerBound(wildcardUpper, true)],
+			prereleaseCore,
+		};
+	}
+	if (operator === "<=") {
+		return {
+			predicates: [wildcardUpper === null ? upperBound(base, true) : upperBound(wildcardUpper, false)],
+			prereleaseCore,
+		};
+	}
+	if (partial.major === null) return { predicates: [], prereleaseCore };
+	if (operator === "~") {
+		const upper =
+			partial.minor === null
+				? { major: partial.major + 1, minor: 0, patch: 0, prerelease: [] }
+				: { major: partial.major, minor: partial.minor + 1, patch: 0, prerelease: [] };
+		return { predicates: [lowerBound(base, true), upperBound(upper, false)], prereleaseCore };
+	}
+	const upper =
+		partial.major > 0
+			? { major: partial.major + 1, minor: 0, patch: 0, prerelease: [] }
+			: partial.minor === null
+				? { major: 1, minor: 0, patch: 0, prerelease: [] }
+				: (partial.minor ?? 0) > 0
+					? { major: 0, minor: (partial.minor ?? 0) + 1, patch: 0, prerelease: [] }
+					: partial.patch === null
+						? { major: 0, minor: 1, patch: 0, prerelease: [] }
+						: { major: 0, minor: 0, patch: (partial.patch ?? 0) + 1, prerelease: [] };
+	return { predicates: [lowerBound(base, true), upperBound(upper, false)], prereleaseCore };
+}
+
+function predicatesForSet(raw: string): { predicates: Predicate[]; prereleaseCores: ReadonlySet<string> } | null {
+	const hyphen = /^(\S+)\s+-\s+(\S+)$/u.exec(raw);
+	if (hyphen !== null) {
+		const left = parsePartial(hyphen[1] ?? "");
+		const right = parsePartial(hyphen[2] ?? "");
+		if (left === null || right === null || left.major === null || right.major === null) return null;
+		const rightUpper = nextWildcard(right);
+		return {
+			predicates: [
+				lowerBound(floor(left), true),
+				rightUpper === null ? upperBound(floor(right), true) : upperBound(rightUpper, false),
+			],
+			prereleaseCores: new Set(
+				[
+					left.prerelease.length > 0 ? core(floor(left)) : null,
+					right.prerelease.length > 0 ? core(floor(right)) : null,
+				].filter((entry): entry is string => entry !== null),
+			),
+		};
+	}
+	const normalized = raw.replace(/(<=|>=|<|>|=|~|\^)\s+/gu, "$1");
+	const tokens = normalized.split(/\s+/u).filter((entry) => entry.length > 0);
+	if (tokens.length === 0) return null;
+	const predicates: Predicate[] = [];
+	const prereleaseCores = new Set<string>();
+	for (const token of tokens) {
+		const parsed = predicatesForToken(token);
+		if (parsed === null) return null;
+		predicates.push(...parsed.predicates);
+		if (parsed.prereleaseCore !== null) prereleaseCores.add(parsed.prereleaseCore);
+	}
+	return { predicates, prereleaseCores };
+}
+
+function parseRange(
+	range: string,
+): ReadonlyArray<{ predicates: Predicate[]; prereleaseCores: ReadonlySet<string> }> | null {
+	const trimmed = range.trim();
+	if (trimmed.length === 0 || trimmed.length > MAX_RANGE_CHARS) return null;
+	const sets = trimmed.split("||");
+	if (sets.some((set) => set.trim().length === 0)) return null;
+	const parsed = sets.map((set) => predicatesForSet(set.trim()));
+	return parsed.every((set) => set !== null) ? (parsed as Array<NonNullable<(typeof parsed)[number]>>) : null;
+}
+
+export function isValidSemVerRange(range: string): boolean {
+	return parseRange(range) !== null;
+}
+
+export function satisfiesSemVerRange(version: string, range: string): boolean {
+	const candidate = parseSemVer(version);
+	const sets = parseRange(range);
+	if (candidate === null || sets === null) return false;
+	return sets.some((set) => {
+		if (candidate.prerelease.length > 0 && !set.prereleaseCores.has(core(candidate))) return false;
+		return set.predicates.every((predicate) => predicate(candidate));
+	});
+}
+
+export interface ClioCompatibilityEvaluation {
+	rangeValid: boolean;
+	satisfied: boolean;
+	runningVersion: string;
+}
+
+export function evaluateClioCompatibility(
+	range: string,
+	runningVersion = getVersionInfo().clio,
+): ClioCompatibilityEvaluation {
+	const rangeValid = isValidSemVerRange(range);
+	return {
+		rangeValid,
+		satisfied: rangeValid && satisfiesSemVerRange(runningVersion, range),
+		runningVersion,
+	};
+}

package/src/domains/extensions/discovery.ts

@@ -1,6 +1,7 @@
 import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import path from "node:path";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { evaluateClioCompatibility } from "./compatibility.js";
 import type {
 	ClioExtensionManifest,
 	ExtensionCandidate,
@@ -166,9 +167,32 @@ export function parseExtensionManifest(
 	const resources = normalizeResources(value.resources);
 	const tools = stringArray(value.tools);
 	const settings = stringArray(value.settings);
-	const compatibility = isRecord(value.compatibility)
-		? { ...(trimString(value.compatibility.clio) ? { clio: trimString(value.compatibility.clio) as string } : {}) }
-		: undefined;
+	let compatibility: ClioExtensionManifest["compatibility"];
+	if (value.compatibility !== undefined) {
+		if (!isRecord(value.compatibility)) {
+			diagnostics.push({ type: "error", message: "compatibility must be an object", path: manifestPath });
+		} else if ("clio" in value.compatibility) {
+			const range = trimString(value.compatibility.clio);
+			if (range === undefined) {
+				diagnostics.push({
+					type: "error",
+					message: "compatibility.clio must be a non-empty semver range",
+					path: manifestPath,
+				});
+			} else {
+				const evaluation = evaluateClioCompatibility(range);
+				if (!evaluation.rangeValid) {
+					diagnostics.push({
+						type: "error",
+						message: `extension ${id ?? "<unknown>"} declares malformed compatibility.clio range '${range}'`,
+						path: manifestPath,
+					});
+				} else {
+					compatibility = { clio: range };
+				}
+			}
+		}
+	}
 	if (!id || !name || !version || !description || diagnostics.some((diag) => diag.type === "error")) {
 		return { diagnostics };
 	}
@@ -183,6 +207,17 @@ export function parseExtensionManifest(
 	if (tools) manifest.tools = tools;
 	if (settings) manifest.settings = settings;
 	if (compatibility && Object.keys(compatibility).length > 0) manifest.compatibility = compatibility;
+	const clioRange = manifest.compatibility?.clio;
+	if (clioRange !== undefined) {
+		const evaluation = evaluateClioCompatibility(clioRange);
+		if (!evaluation.satisfied) {
+			diagnostics.push({
+				type: "error",
+				message: `extension ${manifest.id} requires Clio '${clioRange}', but running Clio version is '${evaluation.runningVersion}'`,
+				path: manifestPath,
+			});
+		}
+	}
 	return { manifest, diagnostics };
 }
 

package/src/domains/extensions/resources.ts

@@ -33,7 +33,7 @@ export function enabledExtensionResourceRoots(
 ): ExtensionResourceRoot[] {
 	const roots: ExtensionResourceRoot[] = [];
 	for (const entry of listInstalledExtensions(cwd)) {
-		if (!entry.enabled || !entry.effective) continue;
+		if (!entry.enabled || !entry.compatible || !entry.effective) continue;
 		const rel = entry.resources[kind];
 		if (!rel) continue;
 		const full = extensionResourcePath(entry.rootPath, rel);