@tikoci/centrs 0.1.3 → 0.1.4

package/src/cli/selection.ts

@@ -65,6 +65,12 @@ export const selectionCommandOptions: readonly CliCommandOption[] = [
 		flag: "--default",
 		description: "Select the reserved `__default__` record.",
 	},
+	{
+		flag: "--quickchr",
+		valueName: "<name>",
+		description:
+			"Target a running quickchr-managed CHR VM by name (repeatable; fans out when repeated). Exclusive of positional targets and CDB selectors; conflicts with direct connection overrides (--host/--port/--username/--password, and --ssh-key where the command has it).",
+	},
 	{
 		flag: "--concurrency",
 		valueName: "<n>",
@@ -81,11 +87,13 @@ export interface SelectionFlags {
 	bbox?: BboxPredicate;
 	all: boolean;
 	default: boolean;
+	/** Repeatable `--quickchr <name>` (named-live-provider; exclusive in v1). */
+	quickchr: string[];
 	concurrency?: number;
 }
 
 export function emptySelectionFlags(): SelectionFlags {
-	return { groups: [], where: [], all: false, default: false };
+	return { groups: [], where: [], all: false, default: false, quickchr: [] };
 }
 
 /** The selection flag tokens, for a command's `--help` table + unknown-flag suggestions. */
@@ -96,6 +104,7 @@ export const selectionFlagTokens = [
 	"--bbox",
 	"--all",
 	"--default",
+	"--quickchr",
 	"--concurrency",
 ] as const;
 
@@ -143,6 +152,9 @@ export function consumeSelectionFlag(
 		case "--bbox":
 			acc.bbox = parseBbox(expectValue(args, index + 1, arg));
 			return index + 1;
+		case "--quickchr":
+			acc.quickchr.push(expectValue(args, index + 1, arg));
+			return index + 1;
 		case "--concurrency": {
 			const raw = expectValue(args, index + 1, arg);
 			const parsed = parseStrictInteger(raw);
@@ -175,26 +187,74 @@ export function buildTargetSelection(
 		where: flags.where,
 		near: flags.near,
 		bbox: flags.bbox,
+		quickchr: flags.quickchr,
 	};
 }
 
+/** True when any CDB selector flag is present (quickchr and positionals excluded). */
+function hasCdbSelector(flags: SelectionFlags): boolean {
+	return (
+		flags.all ||
+		flags.default ||
+		flags.groups.length > 0 ||
+		flags.where.length > 0 ||
+		flags.near !== undefined ||
+		flags.bbox !== undefined
+	);
+}
+
+/**
+ * `--quickchr` exclusivity (v1, `docs/CONSTITUTION.md` → Resolution providers):
+ * a command targets quickchr machines OR CDB/literal targets, never both.
+ * Commands call this after splitting positionals, in both single-target and
+ * fan-out mode; relaxing it later is additive.
+ */
+export function assertQuickchrExclusive(
+	flags: SelectionFlags,
+	targetPositionalCount: number,
+): void {
+	if (flags.quickchr.length === 0) {
+		return;
+	}
+	if (hasCdbSelector(flags) || targetPositionalCount > 0) {
+		throw new CentrsError({
+			code: "usage/conflicting-flags",
+			summary:
+				"`--quickchr` is exclusive: a command targets quickchr machines or CDB/literal targets, not both.",
+			remediation:
+				"Drop the positional target / CDB selector (or the `--quickchr` flag) so the selection has one target source.",
+			context: {
+				quickchr: [...flags.quickchr],
+				positionals: targetPositionalCount,
+			},
+		});
+	}
+}
+
 /**
- * Fan-out mode is keyed on INTENT, not resolved count: any selector flag, or more
- * than one positional target. A plain single-positional call stays single-target
- * (never `FanoutData`); a selector that resolves to one/zero members is still
- * fan-out mode. See `docs/CONSTITUTION.md` (Target selection).
+ * True when any target-taking flag is present, so positionals are operation
+ * args, not targets. Superset of {@link isFanoutMode}'s flag term: a single
+ * `--quickchr` names the target (like a lone positional, still single-target
+ * mode) but already claims the positional slots.
+ */
+export function hasTargetSelector(flags: SelectionFlags): boolean {
+	return hasCdbSelector(flags) || flags.quickchr.length > 0;
+}
+
+/**
+ * Fan-out mode is keyed on INTENT, not resolved count: any selector flag, more
+ * than one positional target, or a repeated `--quickchr`. A plain
+ * single-positional call — and a single `--quickchr <name>` — stays
+ * single-target (never `FanoutData`); a selector that resolves to one/zero
+ * members is still fan-out mode. See `docs/CONSTITUTION.md` (Target selection).
  */
 export function isFanoutMode(
 	flags: SelectionFlags,
 	targetPositionalCount: number,
 ): boolean {
 	return (
-		flags.all ||
-		flags.default ||
-		flags.groups.length > 0 ||
-		flags.where.length > 0 ||
-		flags.near !== undefined ||
-		flags.bbox !== undefined ||
+		hasCdbSelector(flags) ||
+		flags.quickchr.length > 1 ||
 		targetPositionalCount > 1
 	);
 }

package/src/cli/settings.ts

@@ -36,7 +36,7 @@ export const settingsCommand: CliCommandMetadata = {
 	name: "settings",
 	usage: "centrs settings [print|get|set|reset] [args] [flags]",
 	summary:
-		"Manage centrs's own global preferences (centrs.env) and inspect the __default__ CDB record.",
+		"Manage centrs's own global preferences (`centrs.env`) and inspect the `__default__` CDB record.",
 	options: [
 		{
 			flag: "--all",
@@ -47,7 +47,7 @@ export const settingsCommand: CliCommandMetadata = {
 			flag: "--cdb-file",
 			valueName: "<path>",
 			description:
-				"`print` only — CDB to probe for the __default__ record summary (falls back to normal CDB resolution; never centrs.env).",
+				"`print` only — CDB to probe for the `__default__` record summary (falls back to normal CDB resolution; never centrs.env).",
 		},
 		{
 			flag: "--cdb-password",

package/src/cli/transfer.ts

@@ -23,6 +23,7 @@ import {
 	transferOutputFormats,
 	transferVerbs,
 } from "../index.ts";
+import { assertNoQuickchrOverrideConflict } from "../resolver/index.ts";
 import {
 	type CliCommandMetadata,
 	expectValue,
@@ -38,6 +39,7 @@ import {
 	withTips,
 } from "./missing-target.ts";
 import {
+	assertQuickchrExclusive,
 	buildTargetSelection,
 	consumeSelectionFlag,
 	emptySelectionFlags,
@@ -82,8 +84,7 @@ export const transferCommand: CliCommandMetadata = {
 				"Accept a self-signed TLS cert (https/api-ssl) or a new SSH host key. Default verifies.",
 		},
 		{
-			flag: "--force",
-			valueName: "(--overwrite)",
+			flag: "--force / --overwrite",
 			description: "Replace an existing destination. Default refuses it.",
 		},
 		...selectionCommandOptions,
@@ -99,10 +100,10 @@ export const transferCommand: CliCommandMetadata = {
 				"Confirm a mutating fan-out (upload/remove/mkdir/copy) across multiple routers in non-interactive runs.",
 		},
 		{
-			flag: "--verify",
+			flag: "--verify / --no-verify",
 			valueName: "<size|checksum|off>",
 			description:
-				"Post-transfer integrity check. Default size; --no-verify skips.",
+				"Post-transfer integrity check. Default size; `--no-verify` skips.",
 		},
 		{
 			flag: "--type",
@@ -147,6 +148,7 @@ export const transferCommand: CliCommandMetadata = {
 				"Output format. Defaults to text; --json / --yaml shortcuts.",
 		},
 		{ flag: "--json", description: "Shortcut for --format json." },
+		{ flag: "--yaml", description: "Shortcut for --format yaml." },
 		{
 			flag: "--cdb-file",
 			valueName: "<path>",
@@ -479,7 +481,10 @@ function assemblePositionals(
 	selectionFlags: SelectionFlags,
 	fixedVerb?: TransferVerb,
 ): { request: TransferRequest; targetPositionals: readonly string[] } {
-	const hasSelector = isFanoutMode(selectionFlags, 0);
+	// Any target-taking flag (CDB selector or `--quickchr`) claims the target
+	// slots, so every positional belongs to the verb/paths.
+	const hasSelector =
+		isFanoutMode(selectionFlags, 0) || selectionFlags.quickchr.length > 0;
 	let verb: TransferVerb;
 	let targetPositionals: readonly string[];
 	let rest: readonly string[];
@@ -522,9 +527,21 @@ function assemblePositionals(
 
 	const request: TransferRequest = { verb, ...flags };
 	applyVerbPaths(request, verb, rest);
+	assertQuickchrExclusive(selectionFlags, targetPositionals.length);
+	// Direct connection overrides conflict with `--quickchr` globally: reject at
+	// parse time so a repeated `--quickchr` gets one usage error (exit 1), never
+	// per-member failures. The resolver re-checks for library callers.
+	if (selectionFlags.quickchr.length > 0) {
+		assertNoQuickchrOverrideConflict(request, selectionFlags.quickchr[0] ?? "");
+	}
 
-	// Single-target (not fan-out mode) needs exactly one resolved target.
+	// Single-target (not fan-out mode) needs exactly one resolved target: one
+	// positional, or one `--quickchr <name>` (the named-live-provider).
 	if (!isFanoutMode(selectionFlags, targetPositionals.length)) {
+		if (selectionFlags.quickchr.length === 1) {
+			request.quickchr = selectionFlags.quickchr[0];
+			return { request, targetPositionals };
+		}
 		const targetInput = targetPositionals[0];
 		if (!targetInput) {
 			throw missingTargetError({

package/src/cli.ts

@@ -2,9 +2,11 @@
 
 import { apiCommand, runApiCli } from "./cli/api.ts";
 import { btestCommand, runBtestCli } from "./cli/btest.ts";
+import type { CliCommandMetadata } from "./cli/common.ts";
 import { devicesCommand, runDevicesCli } from "./cli/devices.ts";
 import { discoverCommand, runDiscoverCli } from "./cli/discover.ts";
 import { executeCommand, runExecuteCli } from "./cli/execute.ts";
+import { explainCliCommand, runExplainCli } from "./cli/explain.ts";
 import { mcpCommand, runMcpCli } from "./cli/mcp.ts";
 import { retrieveCommand, runRetrieveCli } from "./cli/retrieve.ts";
 import { runSettingsCli, settingsCommand } from "./cli/settings.ts";
@@ -13,18 +15,26 @@ import { runTransferCli, transferCommand } from "./cli/transfer.ts";
 import { asCentrsError, formatCentrsErrorText } from "./errors.ts";
 import { describeCentrs, plannedProtocols, plannedSurfaces } from "./index.ts";
 
-const commandSummaries: ReadonlyArray<{ name: string; summary: string }> = [
+/** Every CLI command's metadata, in help/docs order. `scripts/gen-cli-docs.ts` renders `docs/CLI.md` from this. */
+export const cliCommands: ReadonlyArray<CliCommandMetadata> = [
 	retrieveCommand,
 	executeCommand,
 	apiCommand,
 	transferCommand,
 	terminalCommand,
+	explainCliCommand,
 	devicesCommand,
 	discoverCommand,
 	btestCommand,
 	mcpCommand,
 	settingsCommand,
-].map((command) => ({ name: command.name, summary: command.summary }));
+];
+
+const commandSummaries: ReadonlyArray<{ name: string; summary: string }> =
+	cliCommands.map((command) => ({
+		name: command.name,
+		summary: command.summary,
+	}));
 
 export function renderCliHelp(): string {
 	return [
@@ -75,6 +85,9 @@ export async function runCli(
 		if (command === "download") {
 			return await runTransferCli(rest, { fixedVerb: "download" });
 		}
+		if (command === "explain") {
+			return await runExplainCli(rest);
+		}
 		if (command === "devices") {
 			return await runDevicesCli(rest);
 		}

package/src/core/envelope.ts

@@ -27,7 +27,9 @@ import type { RouterOsProtocol } from "../protocols/index.ts";
 /**
  * Where a resolved setting/identity field came from. Precedence (low → high)
  * is config < comment-kv < env < cli; `cdb` and `arp` describe identity
- * resolution rather than settings precedence.
+ * resolution rather than settings precedence, and `provider` marks a field a
+ * named-live-provider supplied (e.g. `--quickchr`), which bypasses the ladder
+ * entirely (`docs/CONSTITUTION.md` → Resolution providers).
  */
 export type SettingSourceKind =
 	| "default"
@@ -36,7 +38,8 @@ export type SettingSourceKind =
 	| "env"
 	| "cli"
 	| "cdb"
-	| "arp";
+	| "arp"
+	| "provider";
 
 export interface SettingSource {
 	kind: SettingSourceKind;

package/src/core/error-catalog.ts

@@ -234,6 +234,31 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		summary: "A received MNDP datagram could not be decoded.",
 	},
 
+	// quickchr/*
+	{
+		code: "quickchr/package-unavailable",
+		summary: "The optional `@tikoci/quickchr` package is not installed.",
+	},
+	{
+		code: "quickchr/unsupported",
+		summary:
+			"The installed `@tikoci/quickchr` is too old or speaks a newer descriptor version than centrs understands.",
+	},
+	{
+		code: "quickchr/machine-not-found",
+		summary: "No quickchr machine is registered under that name.",
+	},
+	{
+		code: "quickchr/machine-stopped",
+		summary:
+			"The quickchr machine is not running, so it has no live connection facts.",
+	},
+	{
+		code: "quickchr/unsupported-via",
+		summary:
+			"The chosen `--via` has no usable service on the quickchr machine (not forwarded, unavailable, or SSH without batch-capable auth).",
+	},
+
 	// routeros/*
 	{
 		code: "routeros/api-fatal",
@@ -323,6 +348,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		code: "routeros/unsupported-capability",
 		summary: "The chosen protocol does not support this command capability.",
 	},
+	{
+		code: "routeros/version-unsupported",
+		summary:
+			"The device's RouterOS version does not provide the operation this command needs.",
+	},
 
 	// settings/*
 	{
@@ -435,6 +465,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		summary:
 			"Peer verification was disabled via --insecure (TLS / SSH host-key checks skipped).",
 	},
+	{
+		code: "transport/provider-trust",
+		summary:
+			"Peer verification is relaxed for a named-live-provider endpoint (a quickchr VM's self-signed TLS cert / ephemeral SSH host key), trusted by the provider's loopback-forward voucher.",
+	},
 	{
 		code: "transport/local-tool-missing",
 		summary:
@@ -475,6 +510,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		code: "usage/invalid-concurrency",
 		summary: "The --concurrency value must be an integer >= 1.",
 	},
+	{
+		code: "usage/stdin-ignored",
+		summary:
+			"stdin was redirected but the input came from the positional argument, so anything piped in was not analyzed.",
+	},
 	{
 		code: "usage/fanout-not-supported",
 		summary:

package/src/core/preflight.ts

@@ -0,0 +1,306 @@
+/**
+ * Capability/version pre-flight for centrs-generated RouterOS commands (#129).
+ *
+ * centrs sometimes generates a command that assumes a device capability the
+ * device may lack (e.g. `transfer mkdir` → `/file add type=directory`, absent
+ * on older RouterOS). Without a pre-flight that surfaces as a raw protocol
+ * error; with one it becomes a typed `routeros/version-unsupported` error
+ * naming the versions that do support the operation. (Distinct from
+ * `routeros/unsupported-capability`, which is a *protocol*-side gap — the
+ * transport cannot carry the operation at all.)
+ *
+ * Design:
+ * - A {@link CapabilityRequirement} carries the supported
+ *   {@link RouterOsVersionRange} list as **data**. Ranges are inclusive-`min` /
+ *   exclusive-`maxExclusive`, so a backported feature is a list of per-release-
+ *   line minimums (e.g. `[{min:"7.21.4", maxExclusive:"7.22"}, {min:"7.22.2"}]`).
+ *   The grounding for each requirement (CHR run, rosetta changelog/command-diff)
+ *   lives at the requirement's definition site — this module only evaluates.
+ * - The device version comes from a {@link DeviceVersion}: a live read
+ *   ({@link probeDeviceVersion}), the CDB record's stored `version=` comment
+ *   fact ({@link versionFactFromComment} — stale-but-cheap, written by
+ *   `discover --save`/`devices --check`), or the caller.
+ * - An **unknown** version never blocks (crash-early: the device's own error
+ *   still surfaces through the RouterOS error mapping); only a version known to
+ *   be outside every supported range fails, via {@link assertCapability}.
+ *
+ * Version ordering is suffix-aware: `7.23beta1 < 7.23beta2 < 7.23rc1 < 7.23 <
+ * 7.23.1` (RouterOS version format `MAJOR.MINOR[.PATCH][beta|rc N]`). The
+ * comparator tolerates trailing channel/date noise (`"7.21.4 (long-term) …"`),
+ * matching what `/system/resource` reports. Promoted from the integration
+ * harness's `routerOsAtLeast` (`test/integration/chr.ts`), which now delegates
+ * here.
+ */
+
+import { CentrsError } from "../errors.ts";
+import type { ProtocolAdapter } from "../protocols/adapter.ts";
+import { parseRawCommentFacts } from "../resolver/comment-kv.ts";
+
+/** Parsed RouterOS version, ordered by the tuple (major, minor, patch, stage, stageIteration). */
+export interface RouterOsVersionParts {
+	major: number;
+	minor: number;
+	patch: number;
+	/** Prerelease stage rank: beta=0 < rc=1 < release=2. */
+	stageRank: 0 | 1 | 2;
+	/** Iteration within the stage (`beta2` → 2); 0 for a release. */
+	stageIteration: number;
+}
+
+/**
+ * Parse a RouterOS version out of a possibly-noisy string
+ * (`"7.21.4 (long-term) 2026-04-21"` → 7.21.4). Returns `undefined` when no
+ * `major.minor` shape is present.
+ */
+export function parseRouterOsVersion(
+	raw: string,
+): RouterOsVersionParts | undefined {
+	// Bounded digit runs ({1,4}) keep this linear on adversarial input — an
+	// unbounded `\d+` here is a polynomial-ReDoS vector on strings of many
+	// repeated digits (CodeQL js/polynomial-redos). RouterOS version numbers
+	// never approach four digits per field, so the bound is free.
+	//
+	// The `(?<![\d.])` / `(?!\d)` token boundaries keep the (unanchored) match
+	// from latching onto a *fragment* of a larger number: without them
+	// `"12345.67"` matched `"2345.67"` and `"127.0.0.1"` matched `"127.0"`.
+	// They still allow legitimately noisy strings ("7.23.2 (stable)", "v7.23").
+	const match = raw.match(
+		/(?<![\d.])(\d{1,4})\.(\d{1,4})(?:\.(\d{1,4}))?(?:(beta|rc)(\d{1,4}))?(?![\d.])/i,
+	);
+	if (!match) {
+		return undefined;
+	}
+	const stage = match[4]?.toLowerCase();
+	return {
+		major: Number(match[1]),
+		minor: Number(match[2]),
+		patch: Number(match[3] ?? 0),
+		stageRank: stage === undefined ? 2 : stage === "rc" ? 1 : 0,
+		stageIteration: Number(match[5] ?? 0),
+	};
+}
+
+/**
+ * Compare two RouterOS version strings: negative when `a < b`, 0 when equal,
+ * positive when `a > b`. An unparseable version sorts below every parseable
+ * one (and equal to another unparseable one).
+ */
+export function compareRouterOsVersion(a: string, b: string): number {
+	const left = parseRouterOsVersion(a);
+	const right = parseRouterOsVersion(b);
+	if (left === undefined || right === undefined) {
+		return (left === undefined ? 0 : 1) - (right === undefined ? 0 : 1);
+	}
+	return (
+		left.major - right.major ||
+		left.minor - right.minor ||
+		left.patch - right.patch ||
+		left.stageRank - right.stageRank ||
+		left.stageIteration - right.stageIteration
+	);
+}
+
+/** True when `running` ≥ `target`. Unparseable `running` is never ≥ a parseable target. */
+export function routerOsVersionAtLeast(
+	running: string,
+	target: string,
+): boolean {
+	if (
+		parseRouterOsVersion(running) === undefined &&
+		parseRouterOsVersion(target) !== undefined
+	) {
+		return false;
+	}
+	return compareRouterOsVersion(running, target) >= 0;
+}
+
+/**
+ * One contiguous supported window. `min` is inclusive; `maxExclusive` bounds a
+ * backport window (omit it for "this version and everything after").
+ */
+export interface RouterOsVersionRange {
+	min: string;
+	maxExclusive?: string;
+}
+
+/**
+ * True when `version` falls inside `range`. A malformed range is a definition
+ * bug in a {@link CapabilityRequirement}, not a device condition, so it throws
+ * rather than failing open (an unparseable `min` would otherwise sort below
+ * every real version and mark everything supported).
+ */
+export function versionInRange(
+	version: string,
+	range: RouterOsVersionRange,
+): boolean {
+	if (parseRouterOsVersion(range.min) === undefined) {
+		throw new TypeError(
+			`Invalid capability range min ${JSON.stringify(range.min)}; ` +
+				"set CapabilityRequirement.supported[].min to a RouterOS major.minor[.patch] version.",
+		);
+	}
+	if (
+		range.maxExclusive !== undefined &&
+		(parseRouterOsVersion(range.maxExclusive) === undefined ||
+			compareRouterOsVersion(range.min, range.maxExclusive) >= 0)
+	) {
+		throw new TypeError(
+			`Invalid capability range maxExclusive ${JSON.stringify(range.maxExclusive)}; ` +
+				"set CapabilityRequirement.supported[].maxExclusive to a RouterOS version greater than min.",
+		);
+	}
+	if (!routerOsVersionAtLeast(version, range.min)) {
+		return false;
+	}
+	return (
+		range.maxExclusive === undefined ||
+		compareRouterOsVersion(version, range.maxExclusive) < 0
+	);
+}
+
+/**
+ * A capability a centrs-generated command depends on, with the version windows
+ * where RouterOS provides it. Define these next to the consumer (e.g. the
+ * transfer spec owns the `mkdir` requirement) and document the grounding
+ * evidence there.
+ */
+export interface CapabilityRequirement {
+	/** Stable slug for error context, e.g. `file-add-directory`. */
+	capability: string;
+	/** Human phrase for the operation, e.g. "create directories with `/file add type=directory`". */
+	summary: string;
+	/** Windows where the capability exists; supported when ANY range matches. */
+	supported: readonly RouterOsVersionRange[];
+	/** Extra guidance appended to the typed error's remediation. */
+	remediation?: string;
+}
+
+/** Where a pre-flighted device version came from (error context + envelope provenance). */
+export type DeviceVersionSource = "live" | "cdb-fact" | "caller";
+
+/** A device version paired with its provenance. */
+export interface DeviceVersion {
+	version: string;
+	source: DeviceVersionSource;
+}
+
+export type PreflightState = "supported" | "unsupported" | "unknown";
+
+/** Outcome of a capability pre-flight. */
+export interface PreflightVerdict {
+	state: PreflightState;
+	/** Echo of the checked device version, when one was available. */
+	device?: DeviceVersion;
+}
+
+/**
+ * Evaluate a requirement against a device version. `unknown` when no version
+ * is available or it does not parse — callers proceed on `unknown` (the device
+ * still reports its own error, mapped by the RouterOS error vocabulary).
+ */
+export function checkCapability(
+	requirement: CapabilityRequirement,
+	device?: DeviceVersion,
+): PreflightVerdict {
+	if (
+		device === undefined ||
+		parseRouterOsVersion(device.version) === undefined
+	) {
+		return { state: "unknown" };
+	}
+	const supported = requirement.supported.some((range) =>
+		versionInRange(device.version, range),
+	);
+	return { state: supported ? "supported" : "unsupported", device };
+}
+
+/** Render supported windows for humans: `7.21.4–7.22 (excl.), 7.22.2+`. */
+export function renderSupportedRanges(
+	ranges: readonly RouterOsVersionRange[],
+): string {
+	return ranges
+		.map((range) =>
+			range.maxExclusive === undefined
+				? `${range.min}+`
+				: `${range.min}–${range.maxExclusive} (excl.)`,
+		)
+		.join(", ");
+}
+
+/**
+ * Pre-flight gate: throw a typed `routeros/version-unsupported` error when
+ * the device version is known and outside every supported window; otherwise
+ * return the verdict (`unknown` passes — see {@link checkCapability}).
+ */
+export function assertCapability(
+	requirement: CapabilityRequirement,
+	device?: DeviceVersion,
+): PreflightVerdict {
+	const verdict = checkCapability(requirement, device);
+	if (verdict.state !== "unsupported" || verdict.device === undefined) {
+		return verdict;
+	}
+	const supported = renderSupportedRanges(requirement.supported);
+	throw new CentrsError({
+		code: "routeros/version-unsupported",
+		summary: `RouterOS ${verdict.device.version} cannot ${requirement.summary}; it needs ${supported}.`,
+		remediation:
+			(requirement.remediation ? `${requirement.remediation} ` : "") +
+			(verdict.device.source === "cdb-fact"
+				? "The version came from the stored CDB `version=` fact and may be stale; upgrade RouterOS, or refresh the fact if the device was already upgraded."
+				: "Upgrade RouterOS to a supported version."),
+		context: {
+			capability: requirement.capability,
+			version: verdict.device.version,
+			versionSource: verdict.device.source,
+			supported: requirement.supported.map((range) => ({ ...range })),
+		},
+	});
+}
+
+/**
+ * Read a stored device version from a CDB record's comment kv-soup (`version=`
+ * — the derived fact `discover --save` and `devices --check` write). Stale by
+ * nature; provenance is `cdb-fact`.
+ */
+export function versionFactFromComment(
+	comment: string,
+): DeviceVersion | undefined {
+	const version = parseRawCommentFacts(comment)["version"];
+	if (version === undefined || parseRouterOsVersion(version) === undefined) {
+		return undefined;
+	}
+	return { version, source: "cdb-fact" };
+}
+
+/**
+ * Live device-version probe over an already-built adapter. Structured
+ * transports read `/system/resource`; console transports (ssh/mac-telnet) run
+ * `:put [/system/resource/ get version]`. Transport/auth errors propagate —
+ * only a well-formed reply that simply lacks a version yields `undefined`.
+ */
+export async function probeDeviceVersion(
+	adapter: ProtocolAdapter,
+): Promise<DeviceVersion | undefined> {
+	if (adapter.capabilities.retrieve) {
+		const resource = await adapter.getSingleton("/system/resource");
+		const version =
+			typeof resource === "object" && resource !== null
+				? (resource as Record<string, unknown>)["version"]
+				: undefined;
+		if (typeof version === "string" && parseRouterOsVersion(version)) {
+			return { version, source: "live" };
+		}
+		return undefined;
+	}
+	const result = await adapter.execute({
+		path: "/system/resource",
+		command: "print",
+		script: ":put [/system/resource/ get version]",
+	});
+	const version = result.ret?.trim();
+	if (version && parseRouterOsVersion(version)) {
+		return { version, source: "live" };
+	}
+	return undefined;
+}