@tikoci/centrs 0.1.7 → 0.1.8-next.0

package/src/retrieve.ts

@@ -5,19 +5,31 @@ import type {
 	CommonSettingsMeta,
 	SettingSource as CoreSettingSource,
 	EnvelopeValidationMeta,
+	ValidationTrace,
 } from "./core/envelope.ts";
+import { notReachedReason } from "./core/envelope.ts";
 import {
 	extractCompletionNames,
 	inspectArgumentNames,
 	inspectChildren,
 	inspectChildrenOrEmpty,
 	inspectCompletions,
+	inspectWhereBooleans,
 	isArgumentNode,
 	isCommandNode,
 	pathTokens,
 } from "./core/inspect.ts";
+import {
+	compileQueryWords,
+	type ParsedQuery,
+	parseQueries,
+} from "./core/query.ts";
 import { toYaml } from "./core/yaml.ts";
-import { CentrsError, serializeCentrsError } from "./errors.ts";
+import {
+	CentrsError,
+	formatCentrsErrorText,
+	serializeCentrsError,
+} from "./errors.ts";
 import {
 	createProtocolAdapter,
 	type ProtocolAdapter,
@@ -50,7 +62,12 @@ import {
 	toCoreSource,
 } from "./resolver/index.ts";
 
-export const retrieveOutputFormats = ["text", "json", "yaml"] as const;
+export const retrieveOutputFormats = [
+	"text",
+	"json",
+	"yaml",
+	"ndjson",
+] as const;
 export type RetrieveOutputFormat = (typeof retrieveOutputFormats)[number];
 
 export interface RetrieveRequest {
@@ -75,8 +92,10 @@ export interface RetrieveRequest {
 	attributes?: string | readonly string[];
 	allAttributes?: boolean;
 	listAttributes?: boolean;
-	filter?: string;
-	query?: string;
+	/** Alias of `query`; both lists are AND-ed together. */
+	filter?: string | readonly string[];
+	/** Row filters written as after `print where` (`disabled`, `mtu>=1500 and !dynamic`); several are AND-ed. */
+	query?: string | readonly string[];
 	maxResultsBytes?: number;
 	cdbFile?: string;
 	cdbPassword?: string;
@@ -86,6 +105,22 @@ export interface RetrieveRequest {
 	group?: string;
 	/** Bounded worker-pool size for group fanout (defaults are transport-aware). */
 	concurrency?: number;
+	/** Keep the menu's rows current over native-api `listen` (`retrieveFollow`). */
+	follow?: boolean;
+	/** `--follow` only: `.id` sweep period (`10s` default; `0` turns it off). */
+	sweep?: string | number;
+	/** Read the menu again every interval (`retrieveSample`), e.g. `5s`. */
+	sample?: string | number;
+	/** `--follow`: stop after this many `live` frames; `--sample`: after this many samples. */
+	count?: number;
+	/** `--follow`/`--sample`: wall-clock bound counted from the end of validation (e.g. `30s`). */
+	duration?: string | number;
+	/** Overall readiness/condition deadline; consumed by `retrieveWait()`. */
+	wait?: string | number;
+	/** Same grammar as `--query`: succeed when any selected row matches. */
+	until?: string | readonly string[];
+	/** Succeed on a completed read with zero selected rows. */
+	untilEmpty?: boolean;
 }
 
 export interface RetrieveWarning {
@@ -104,8 +139,116 @@ export interface RetrieveRequestSummary {
 	timeoutMs: number;
 	format: RetrieveOutputFormat;
 	maxResultsBytes?: number;
+	/** The `--query` expressions, as given. */
+	query?: readonly string[];
+	/** Present when the request is a `--follow`. */
+	follow?: RetrieveFollowSettings;
+	/** Present when the request is a `--sample`. */
+	sample?: RetrieveSampleSettings;
+	wait?: RetrieveWaitSettings;
+}
+
+export interface RetrieveWaitSettings {
+	deadlineMs: number;
+	intervalMs: number;
+	until: readonly string[];
+	untilEmpty: boolean;
+}
+
+export interface RetrieveWaitMeta {
+	stopReason:
+		| "ready"
+		| "condition-met"
+		| "deadline-elapsed"
+		| "interrupted"
+		| "failed";
+	elapsedMs: number;
+	attempts: number;
+	observations: number;
+}
+
+/** The resolved cadence and bounds of a `--sample`. */
+export interface RetrieveSampleSettings {
+	/** Time between the starts of two reads; a slow read delays the next one. */
+	intervalMs: number;
+	count?: number;
+	durationMs?: number;
+}
+
+/** The resolved bounds of a `--follow`. */
+export interface RetrieveFollowSettings {
+	/** `.id` sweep period; `0` = off. */
+	sweepMs: number;
+	count?: number;
+	durationMs?: number;
+}
+
+/** Why a `--follow` ended. */
+export type RetrieveFollowStopReason =
+	| "completed"
+	| "routeros-error"
+	| "count-reached"
+	| "duration-elapsed"
+	| "interrupted"
+	| "transport-error";
+
+/** Counts carried by a `--follow` summary (also its `data`). */
+export interface RetrieveFollowCounts {
+	/** Every frame line, snapshot and live. */
+	frames: number;
+	/** Frames before `synced`. */
+	snapshot: number;
+	/** `live` frames after `synced`; `--count` counts these. */
+	changes: number;
+	/** Completed `.id` sweeps. */
+	sweeps: number;
+	/** Whether the bootstrap finished before the follow ended. */
+	synced: boolean;
+}
+
+export interface RetrieveFollowSummary extends RetrieveFollowCounts {
+	stopReason: RetrieveFollowStopReason;
+	durationMs: number;
+}
+
+/** Why a `--sample` ended: it never completes on its own. */
+export type RetrieveSampleStopReason = Exclude<
+	RetrieveFollowStopReason,
+	"completed"
+>;
+
+/** A `--sample` summary (also its `data`). */
+export interface RetrieveSampleSummary {
+	stopReason: RetrieveSampleStopReason;
+	/** Sample lines emitted; a read still in flight at the stop is not one. */
+	samples: number;
+	durationMs: number;
 }
 
+/**
+ * Per-line marker on `--follow` and `--sample` output
+ * (`commands/retrieve/README.md` → Follow, Sample). A `frame` is one row
+ * change: `upsert` carries the latest full row, `removed` carries
+ * `data: null`; `id` is the row identity even when the projection leaves `.id`
+ * out of `data`. A `sample` is one complete read; `at` is when it was sent
+ * (host clock) and `readMs` how long it took. The two summaries are told apart
+ * by their counts (`frames` vs `samples`).
+ */
+export type RetrieveStreamMeta =
+	| { kind: "notice" }
+	| {
+			kind: "frame";
+			index: number;
+			phase: "snapshot" | "live";
+			change: "upsert" | "removed";
+			id: string;
+			source: "print" | "listen" | "sweep" | "membership";
+	  }
+	| { kind: "synced"; rows: number }
+	| { kind: "sample"; index: number; at: string; readMs: number }
+	| ({ kind: "summary" } & RetrieveFollowSummary)
+	| ({ kind: "summary" } & RetrieveSampleSummary);
+
 export interface RetrieveOperationMeta {
 	kind: "attributes" | "data";
 	objectCount: number;
@@ -114,6 +257,10 @@ export interface RetrieveOperationMeta {
 		username?: string;
 		passwordProvided: boolean;
 	};
+	/** Present only on `--follow` and `--sample` output. */
+	stream?: RetrieveStreamMeta;
+	/** The bounded waiter outcome; a watch duration never satisfies a condition. */
+	wait?: RetrieveWaitMeta;
 }
 
 export type RetrieveEnvelope = CentrsEnvelope<unknown, RetrieveOperationMeta>;
@@ -123,7 +270,7 @@ export type RetrieveSuccessEnvelope = CentrsSuccessEnvelope<
 >;
 export type RetrieveErrorEnvelope = CentrsErrorEnvelope<RetrieveOperationMeta>;
 
-interface RetrieveInspection {
+export interface RetrieveInspection {
 	command: "get" | "print";
 	singleton: boolean;
 }
@@ -149,15 +296,108 @@ export interface ResolvedRetrieveRequest {
 	allAttributes: boolean;
 	listAttributes: boolean;
 	verbose: boolean;
+	/** `--query`, parsed offline; compiled to words once the device says which bare names are booleans. */
+	query?: ResolvedRetrieveQuery;
+	follow?: RetrieveFollowSettings;
+	sample?: RetrieveSampleSettings;
+	wait?: RetrieveWaitSettings;
 	warnings: readonly RetrieveWarning[];
 }
 
+export interface ResolvedRetrieveQuery {
+	expressions: readonly string[];
+	parsed: ParsedQuery;
+}
+
+/**
+ * What a data read needs after validation: the path's shape (undefined under
+ * `--validate=false`) and the compiled `--query` words.
+ */
+export interface RetrieveReadPlan {
+	inspection: RetrieveInspection | undefined;
+	query?: readonly string[];
+}
+
+export interface RetrieveOptions {
+	/**
+	 * Called once resolution succeeds, before any connection. A caller that
+	 * catches the later throw uses it to keep the resolved target, via and
+	 * setting sources in its error envelope.
+	 */
+	onResolved?: (resolved: ResolvedRetrieveRequest) => void;
+	/**
+	 * Receives the gate's result the moment validation settles, so an error
+	 * envelope built after a later throw reports the validation that ran.
+	 */
+	trace?: ValidationTrace;
+}
+
 export async function retrieve(
 	request: RetrieveRequest,
 	env: Record<string, string | undefined> = Bun.env,
+	options: RetrieveOptions = {},
 ): Promise<RetrieveSuccessEnvelope> {
+	if (request.wait !== undefined) {
+		throw new CentrsError({
+			code: "input/invalid-command",
+			summary:
+				"Use `retrieveWait()` for a bounded readiness or condition wait.",
+			remediation:
+				"Call `retrieveWait(request)` (library) or `centrs retrieve … --wait 30s` (CLI); inspect its success or failure envelope.",
+		});
+	}
+	if (request.follow) {
+		throw new CentrsError({
+			code: "input/invalid-command",
+			summary:
+				"`follow` yields a stream of envelopes instead of one `retrieve` result.",
+			remediation:
+				"Consume it with `retrieveFollow()` (library) or `centrs retrieve … --follow` (CLI): snapshot frames, `synced`, live frames, then a summary.",
+			context: { capability: "follow" },
+		});
+	}
+	if (request.sample !== undefined) {
+		throw new CentrsError({
+			code: "input/invalid-command",
+			summary:
+				"`sample` yields a stream of envelopes instead of one `retrieve` result.",
+			remediation:
+				"Consume it with `retrieveSample()` (library) or `centrs retrieve … --sample <interval>` (CLI): one line per complete read, then a summary.",
+			context: { capability: "sample" },
+		});
+	}
 	const resolved = await resolveRetrieveRequest(request, env);
-	return runResolvedRetrieve(resolved);
+	options.onResolved?.(resolved);
+	return runResolvedRetrieve(resolved, options.trace);
+}
+
+/**
+ * {@link retrieve} as an envelope that never throws. A failure after resolution
+ * carries the resolved target, via and setting sources
+ * ({@link buildRetrieveErrorEnvelopeFromResolved}); a failure before it keeps
+ * only the caller's input ({@link buildRetrieveErrorEnvelope}).
+ */
+export async function retrieveEnvelope(
+	request: RetrieveRequest,
+	env: Record<string, string | undefined> = Bun.env,
+	options: RetrieveOptions = {},
+): Promise<RetrieveEnvelope> {
+	let resolved: ResolvedRetrieveRequest | undefined;
+	const trace = options.trace ?? {};
+	try {
+		return await retrieve(request, env, {
+			...options,
+			trace,
+			onResolved: (value) => {
+				resolved = value;
+				options.onResolved?.(value);
+			},
+		});
+	} catch (error) {
+		return resolved
+			? buildRetrieveErrorEnvelopeFromResolved(resolved, error, trace)
+			: buildRetrieveErrorEnvelope(request, error);
+	}
 }
 
 /**
@@ -169,10 +409,9 @@ export async function retrieve(
  */
 export async function runResolvedRetrieve(
 	resolved: ResolvedRetrieveRequest,
+	trace: ValidationTrace = {},
 ): Promise<RetrieveSuccessEnvelope> {
 	const warnings: RetrieveWarning[] = [...resolved.warnings];
-	let availableAttributes: string[] | undefined;
-	let inspection: RetrieveInspection | undefined;
 	const backend = createProtocolAdapter({
 		protocol: resolved.via.value,
 		host: resolved.target.host,
@@ -186,78 +425,46 @@ export async function runResolvedRetrieve(
 	});
 
 	try {
-		if (resolved.listAttributes || resolved.validate.value) {
-			inspection = await inspectRetrievePath(resolved, backend);
-		}
-
-		if (
-			resolved.listAttributes ||
-			(resolved.validate.value && resolved.attributes.length > 0)
-		) {
-			availableAttributes = await inspectAttributes(
+		if (resolved.listAttributes) {
+			const availableAttributes = await inspectAttributes(
 				resolved,
-				inspection ?? (await inspectRetrievePath(resolved, backend)),
+				await inspectRetrievePath(resolved, backend),
 				backend,
 			);
-		}
-
-		if (resolved.listAttributes) {
+			const validation: EnvelopeValidationMeta = {
+				enabled: true,
+				source: "live /console/inspect request=child+completion",
+				result: "passed",
+				availableAttributes,
+			};
+			trace.validation = validation;
 			const envelope = buildSuccessEnvelope(
 				resolved,
 				{
 					kind: "attributes",
-					data: availableAttributes ?? [],
-				},
-				{
-					enabled: true,
-					source: "live /console/inspect request=child+completion",
-					availableAttributes: availableAttributes ?? [],
+					data: availableAttributes,
 				},
+				validation,
 				warnings,
 			);
 			return applyMaxResultsBudget(envelope);
 		}
 
-		if (
-			resolved.validate.value &&
-			availableAttributes &&
-			resolved.attributes.length > 0
-		) {
-			const missing = resolved.attributes.filter(
-				(attribute) => !availableAttributes?.includes(attribute),
-			);
-			if (missing.length > 0) {
-				throw new CentrsError({
-					code: "validation/unknown-attribute",
-					summary: `Unknown RouterOS attribute ${missing.join(", ")} for ${resolved.path}.`,
-					remediation:
-						"Check the attribute name, or use `--list-attributes` to inspect the available properties first.",
-					context: {
-						path: resolved.path,
-						parameter: missing[0],
-						requestedAttributes: resolved.attributes,
-						availableAttributes,
-					},
-				});
-			}
-		}
-
-		const data = await executeRetrieve(resolved, backend, inspection);
+		const { validation, ...plan } = await validateRetrieveRead(
+			resolved,
+			backend,
+		);
+		// Recorded BEFORE the read, so a RouterOS fault or transport drop below
+		// reports the gate that passed rather than a guess (GH#435).
+		trace.validation = validation;
+		const data = await executeRetrieve(resolved, backend, plan);
 		const envelope = buildSuccessEnvelope(
 			resolved,
 			{
 				kind: "data",
 				data,
 			},
-			{
-				enabled: resolved.validate.value,
-				source: resolved.validate.value
-					? availableAttributes
-						? "live /console/inspect request=child+completion"
-						: "live /console/inspect request=child"
-					: "disabled",
-				availableAttributes,
-			},
+			validation,
 			warnings,
 		);
 		return applyMaxResultsBudget(envelope);
@@ -266,6 +473,53 @@ export async function runResolvedRetrieve(
 	}
 }
 
+/**
+ * The inspect half of a data read: the path's shape (singleton or list) and
+ * the requested attributes, checked once. `--validate=false` skips both.
+ * Shared by one-shot retrieve and `--sample`, which reads many times after it.
+ */
+export async function validateRetrieveRead(
+	resolved: ResolvedRetrieveRequest,
+	backend: ProtocolAdapter,
+): Promise<RetrieveReadPlan & { validation: EnvelopeValidationMeta }> {
+	if (!resolved.validate.value) {
+		return {
+			inspection: undefined,
+			query: compileQueryWithoutValidation(resolved),
+			validation: { enabled: false, source: "disabled" },
+		};
+	}
+	const inspection = await inspectRetrievePath(resolved, backend);
+	if (resolved.query && inspection.singleton) {
+		throw singletonQueryError(resolved, resolved.query);
+	}
+	const availableAttributes =
+		resolved.attributes.length > 0 || resolved.query !== undefined
+			? await assertKnownAttributes(resolved, inspection, backend)
+			: undefined;
+	const query =
+		resolved.query && availableAttributes
+			? await compileValidatedQuery(
+					resolved,
+					resolved.query,
+					availableAttributes,
+					backend,
+				)
+			: undefined;
+	return {
+		inspection,
+		query,
+		validation: {
+			enabled: true,
+			source: availableAttributes
+				? "live /console/inspect request=child+completion"
+				: "live /console/inspect request=child",
+			result: "passed",
+			availableAttributes,
+		},
+	};
+}
+
 export function buildRetrieveErrorEnvelope(
 	request: RetrieveRequest,
 	error: unknown,
@@ -310,6 +564,7 @@ export function buildRetrieveErrorEnvelope(
 export function buildRetrieveErrorEnvelopeFromResolved(
 	resolved: ResolvedRetrieveRequest,
 	error: unknown,
+	trace?: ValidationTrace,
 ): RetrieveErrorEnvelope {
 	const centrsError =
 		error instanceof CentrsError
@@ -322,11 +577,10 @@ export function buildRetrieveErrorEnvelopeFromResolved(
 					cause: error,
 				});
 
-	const meta = metaFromResolved(resolved, {
-		enabled: resolved.validate.value,
-		source: resolved.validate.value ? "live /console/inspect" : "disabled",
-		result: "failed",
-	});
+	const meta = metaFromResolved(
+		resolved,
+		trace?.validation ?? unsettledValidationMeta(resolved, centrsError),
+	);
 
 	return {
 		ok: false,
@@ -337,6 +591,53 @@ export function buildRetrieveErrorEnvelopeFromResolved(
 	};
 }
 
+const RETRIEVE_DEVICE_STAGE_SOURCE = "live /console/inspect";
+
+/**
+ * `meta.validation` for a failure with no settled gate result: the gate
+ * refused, or something stopped it before it answered (GH#435).
+ *
+ * Every retrieve gate refusal is a `CentrsError` the gate itself raised from
+ * an inspect answer: `validation/*`, and the singleton `--query` refusal
+ * (`usage/conflicting-flags`). A `transport/*` or `auth/*` failure means the
+ * device never answered; a `routeros/*` error is a device answer that is not
+ * a verdict; `internal/*` is a centrs defect. Those four report no `result`.
+ */
+function unsettledValidationMeta(
+	resolved: ResolvedRetrieveRequest,
+	error: CentrsError,
+): EnvelopeValidationMeta {
+	if (!resolved.validate.value) {
+		return { enabled: false, source: "disabled" };
+	}
+	if (/^(transport|auth|routeros|internal)\//.test(error.code)) {
+		return {
+			enabled: true,
+			source: RETRIEVE_DEVICE_STAGE_SOURCE,
+			stages: [
+				{
+					stage: "device",
+					source: RETRIEVE_DEVICE_STAGE_SOURCE,
+					result: "skipped",
+					reason: notReachedReason(error.code),
+				},
+			],
+		};
+	}
+	return {
+		enabled: true,
+		source: RETRIEVE_DEVICE_STAGE_SOURCE,
+		result: "failed",
+		stages: [
+			{
+				stage: "device",
+				source: RETRIEVE_DEVICE_STAGE_SOURCE,
+				result: "failed",
+			},
+		],
+	};
+}
+
 export function renderRetrieveEnvelope(
 	envelope: RetrieveEnvelope,
 	format: RetrieveOutputFormat,
@@ -347,10 +648,17 @@ export function renderRetrieveEnvelope(
 			return JSON.stringify(envelope, null, 2);
 		case "yaml":
 			return toYaml(envelope);
+		case "ndjson":
+			return JSON.stringify(envelope);
 		case "text":
-			return envelope.ok
-				? renderRetrieveSuccessText(envelope, options)
-				: renderRetrieveErrorText(envelope, options);
+			return (
+				(envelope.ok
+					? renderRetrieveSuccessText(envelope, options)
+					: formatCentrsErrorText(envelope.error, options)) +
+				(envelope.meta.operation?.wait
+					? `\nwait: ${envelope.meta.operation.wait.stopReason}; ${envelope.meta.operation.wait.elapsedMs}ms; ${envelope.meta.operation.wait.attempts} attempt(s), ${envelope.meta.operation.wait.observations} observation(s)`
+					: "")
+			);
 		default:
 			return exhaustiveOutputFormat(format);
 	}
@@ -416,26 +724,7 @@ function renderRetrieveSuccessText(
 	return lines.join("\n");
 }
 
-function renderRetrieveErrorText(
-	envelope: RetrieveErrorEnvelope,
-	options: { verbose?: boolean },
-): string {
-	const { error } = envelope;
-	const lines = [`[${error.code}] ${error.summary}`];
-
-	if (error.remediation) {
-		lines.push(`Fix: ${error.remediation}`);
-	}
-
-	if (options.verbose && error.context) {
-		lines.push("");
-		lines.push(JSON.stringify(error.context, null, 2));
-	}
-
-	return lines.join("\n");
-}
-
-function retrieveRequestSummary(
+export function retrieveRequestSummary(
 	resolved: ResolvedRetrieveRequest,
 ): RetrieveRequestSummary {
 	return {
@@ -448,6 +737,10 @@ function retrieveRequestSummary(
 		timeoutMs: resolved.timeoutMs.value,
 		format: resolved.format.value,
 		maxResultsBytes: resolved.maxResultsBytes?.value,
+		...(resolved.query ? { query: resolved.query.expressions } : {}),
+		...(resolved.follow ? { follow: resolved.follow } : {}),
+		...(resolved.sample ? { sample: resolved.sample } : {}),
+		...(resolved.wait ? { wait: resolved.wait } : {}),
 	};
 }
 
@@ -455,7 +748,7 @@ function retrieveRequestSummary(
  * Common `target` / `via` / `settings` meta for a resolved target. Shared by
  * success and per-target error envelopes so both carry identical provenance.
  */
-function metaFromResolved(
+export function metaFromResolved(
 	resolved: ResolvedRetrieveRequest,
 	validation: EnvelopeValidationMeta,
 	operation?: RetrieveOperationMeta,
@@ -513,7 +806,7 @@ function metaFromResolved(
 	};
 }
 
-function buildSuccessEnvelope(
+export function buildSuccessEnvelope(
 	resolved: ResolvedRetrieveRequest,
 	result: { kind: "attributes" | "data"; data: unknown },
 	validation: EnvelopeValidationMeta,
@@ -538,7 +831,7 @@ function buildSuccessEnvelope(
 	};
 }
 
-function applyMaxResultsBudget(
+export function applyMaxResultsBudget(
 	envelope: RetrieveSuccessEnvelope,
 ): RetrieveSuccessEnvelope {
 	const operation = envelope.meta.operation;
@@ -591,20 +884,20 @@ export function validateRetrieveRequestShape(
 		});
 	}
 
-	if (request.filter !== undefined || request.query !== undefined) {
+	const query = resolveRetrieveQuery(request);
+	resolveWaitSettings(request);
+	if (query && request.listAttributes) {
 		throw new CentrsError({
-			code: "validation/not-implemented",
-			summary:
-				"`--filter` and `--query` are not implemented yet for `retrieve`.",
+			code: "usage/conflicting-flags",
+			summary: "`--list-attributes` cannot be combined with `--query`.",
 			remediation:
-				"Remove the flag for now, or narrow the request with `--attribute` and `--max-results` instead.",
-			context: {
-				filter: request.filter,
-				query: request.query,
-			},
+				"Run `--list-attributes` by itself to see the property names, then filter with `--query`.",
+			context: { flag: "--query" },
 		});
 	}
 
+	assertStreamShape(request);
+
 	const attributeSelections = normalizeAttributeSelection(request);
 	if (request.allAttributes && attributeSelections.length > 0) {
 		throw new CentrsError({
@@ -632,6 +925,195 @@ export function validateRetrieveRequestShape(
 	return attributeSelections;
 }
 
+/**
+ * `--follow`/`--sample` flag pairings, checked before any network work: the
+ * two are exclusive, their bounds need one of them, and a byte budget or an
+ * attribute listing has no meaning on a stream.
+ */
+function assertStreamShape(request: RetrieveRequest): void {
+	const sample = request.sample !== undefined && request.wait === undefined;
+	if (request.follow && sample) {
+		throw new CentrsError({
+			code: "usage/conflicting-flags",
+			summary: "`--follow` cannot be combined with `--sample`.",
+			remediation:
+				"Use `--follow` for object changes RouterOS announces, or `--sample <interval>` to read the menu on a timer (counters, state `listen` never reports).",
+			context: { flag: "--sample" },
+		});
+	}
+	if (!request.follow) {
+		const orphan = (
+			[
+				["--sweep", request.sweep],
+				["--count", sample ? undefined : request.count],
+				["--duration", sample ? undefined : request.duration],
+			] as const
+		).find(([, value]) => value !== undefined);
+		if (orphan) {
+			const followOnly = orphan[0] === "--sweep";
+			throw new CentrsError({
+				code: "usage/conflicting-flags",
+				summary: `\`${orphan[0]}\` only applies to ${followOnly ? "`--follow`" : "`--follow` or `--sample`"}.`,
+				remediation: followOnly
+					? "Add `--follow` to follow the menu, or drop `--sweep`."
+					: `Add \`--follow\` or \`--sample <interval>\`, or drop \`${orphan[0]}\` for a one-shot read.`,
+				context: { flag: orphan[0] },
+			});
+		}
+		if (!sample) return;
+	}
+	const mode = request.follow ? "--follow" : "--sample";
+	const conflict = request.listAttributes
+		? "--list-attributes"
+		: request.maxResultsBytes !== undefined
+			? "--max-results"
+			: undefined;
+	if (conflict) {
+		throw new CentrsError({
+			code: "usage/conflicting-flags",
+			summary: `\`${mode}\` cannot be combined with \`${conflict}\`.`,
+			remediation: `Run \`${conflict}\` as a one-shot read, then use \`${mode}\` without it.`,
+			context: { flag: conflict },
+		});
+	}
+	if (
+		request.count !== undefined &&
+		(!Number.isInteger(request.count) || request.count < 1)
+	) {
+		throw new CentrsError({
+			code: "settings/invalid-integer",
+			summary: `\`--count\` must be a positive integer. Received: ${request.count}`,
+			remediation: request.follow
+				? "Pass how many live changes to wait for, e.g. `--count 1` for the next change."
+				: "Pass how many samples to take, e.g. `--count 3`.",
+			context: { flag: "--count", count: request.count },
+		});
+	}
+}
+
+function resolveWaitSettings(
+	request: RetrieveRequest,
+): RetrieveWaitSettings | undefined {
+	const until = request.until === undefined ? [] : [request.until].flat();
+	if (until.length > 0) parseQueries(until, "--until");
+	if (request.wait === undefined) {
+		if (until.length > 0 || request.untilEmpty)
+			throw new CentrsError({
+				code: "usage/conflicting-flags",
+				summary: "`--until` and `--until-empty` need a `--wait` deadline.",
+				remediation:
+					"Add an overall bound, e.g. `--wait 2m`, so the condition cannot wait forever.",
+			});
+		return undefined;
+	}
+	const conflict = request.follow
+		? "--follow"
+		: request.count !== undefined
+			? "--count"
+			: request.duration !== undefined
+				? "--duration"
+				: request.listAttributes
+					? "--list-attributes"
+					: until.length > 0 && request.untilEmpty
+						? "--until-empty"
+						: undefined;
+	if (conflict)
+		throw new CentrsError({
+			code: "usage/conflicting-flags",
+			summary: `\`--wait\` cannot be combined with \`${conflict}\`.`,
+			remediation:
+				"Use `--wait` for a readiness/condition deadline, `--sample` for its polling cadence, and either `--until` or `--until-empty` for a condition.",
+		});
+	// A unit is required for the same reason as `--sample`: a bare `30` would
+	// be a 30 ms deadline, which expires before validation completes.
+	const text = String(request.wait).trim();
+	const deadlineMs = /^\d+$/.test(text) ? -1 : parseDuration(text);
+	if (deadlineMs <= 0)
+		throw new CentrsError({
+			code: "settings/invalid-timeout",
+			summary: `\`--wait\` needs a positive deadline with a unit. Received: ${text}`,
+			remediation:
+				"Pass an overall duration such as `--wait 30s` or `--wait 5m`.",
+			context: { flag: "--wait", value: text },
+		});
+	return {
+		deadlineMs,
+		intervalMs:
+			request.sample === undefined
+				? 1_000
+				: parseStreamInterval("--sample", request.sample),
+		until,
+		untilEmpty: request.untilEmpty ?? false,
+	};
+}
+
+function resolveFollowSettings(
+	request: RetrieveRequest,
+): RetrieveFollowSettings | undefined {
+	if (!request.follow) return undefined;
+	const durationMs =
+		request.duration === undefined
+			? undefined
+			: parseDuration(String(request.duration));
+	return {
+		sweepMs:
+			request.sweep === undefined
+				? FOLLOW_SWEEP_DEFAULT_MS
+				: parseStreamInterval("--sweep", request.sweep),
+		...(request.count !== undefined ? { count: request.count } : {}),
+		...(durationMs !== undefined ? { durationMs } : {}),
+	};
+}
+
+/** `--sweep` default (#396 slice decisions, 2026-10-08). */
+export const FOLLOW_SWEEP_DEFAULT_MS = 10_000;
+
+function resolveSampleSettings(
+	request: RetrieveRequest,
+): RetrieveSampleSettings | undefined {
+	if (request.sample === undefined || request.wait !== undefined)
+		return undefined;
+	const durationMs =
+		request.duration === undefined
+			? undefined
+			: parseDuration(String(request.duration));
+	return {
+		intervalMs: parseStreamInterval("--sample", request.sample),
+		...(request.count !== undefined ? { count: request.count } : {}),
+		...(durationMs !== undefined ? { durationMs } : {}),
+	};
+}
+
+/**
+ * A `--sample` or `--sweep` period needs a unit: RouterOS reads a bare
+ * `interval=5` as seconds while centrs durations read a bare number as
+ * milliseconds, so `--sample 5` is refused rather than guessed. `--sweep 0`
+ * (off) is the one bare number allowed; `--sample` must be above zero.
+ */
+function parseStreamInterval(
+	flag: "--sample" | "--sweep",
+	value: string | number,
+): number {
+	const text = String(value).trim();
+	const off = flag === "--sweep" && text === "0";
+	const intervalMs = off ? 0 : /^\d+$/.test(text) ? -1 : parseDuration(text);
+	if (intervalMs < 0 || (flag === "--sample" && intervalMs === 0)) {
+		throw new CentrsError({
+			code: "settings/invalid-timeout",
+			summary:
+				flag === "--sample"
+					? `\`--sample\` needs a positive interval with a unit. Received: ${text}`
+					: `\`--sweep\` needs a unit (or \`0\` to turn it off). Received: ${text}`,
+			remediation:
+				flag === "--sample"
+					? "Pass the time between reads with its unit, e.g. `--sample 5s` or `--sample 500ms`."
+					: "Pass the sweep period with its unit, e.g. `--sweep 10s` or `--sweep 500ms`, or `--sweep 0` to turn it off.",
+			context: { flag, value: text },
+		});
+	}
+	return intervalMs;
+}
+
 /**
  * Build a {@link ResolvedRetrieveRequest} from the static request plus an
  * already-resolved CDB record (or `undefined` for a literal target). Fanout
@@ -725,6 +1207,10 @@ export function buildResolvedRetrieve(
 		allAttributes: request.allAttributes ?? false,
 		listAttributes: request.listAttributes ?? false,
 		verbose: request.verbose ?? false,
+		query: resolveRetrieveQuery(request),
+		follow: resolveFollowSettings(request),
+		sample: resolveSampleSettings(request),
+		wait: resolveWaitSettings(request),
 		warnings: connection
 			? [...connection.warnings]
 			: (cdbResolution?.warnings ?? []),
@@ -788,6 +1274,9 @@ export function resolveRetrieveGlobalContext(
 			timeoutMs: timeoutMs.value,
 			format: format.value,
 			maxResultsBytes: maxResultsBytes?.value,
+			...(queryExpressions(request).length > 0
+				? { query: queryExpressions(request) }
+				: {}),
 		},
 		settings: {
 			via: toCoreSource(via.source),
@@ -885,11 +1374,13 @@ function resolveProtocol(
 	cdb?: CdbResolution,
 	config: Record<string, string | undefined> = {},
 ): ResolvedSetting<RouterOsProtocol> {
+	// A follow infers native-api when `via` is unset (REST cannot follow); a
+	// `via` from any source still wins, and `retrieveFollow` rejects non-native.
 	const via = resolveStringSetting(
 		request.via,
 		env,
 		"CENTRS_VIA",
-		"rest-api",
+		request.follow ? "native-api" : "rest-api",
 		"via",
 		undefined,
 		cdb?.overrides.via,
@@ -974,7 +1465,7 @@ function resolveFormat(
  * trap. Attribute/completion discovery does NOT use the swallowing probe — traps
  * there surface as-is.
  */
-async function inspectRetrievePath(
+export async function inspectRetrievePath(
 	resolved: ResolvedRetrieveRequest,
 	backend: ProtocolAdapter,
 ): Promise<RetrieveInspection> {
@@ -1016,6 +1507,130 @@ async function inspectRetrievePath(
 	};
 }
 
+/**
+ * Inspect the menu's attribute names and reject requested ones it lacks with
+ * `validation/unknown-attribute`. Shared by one-shot retrieve and `--follow`.
+ */
+export async function assertKnownAttributes(
+	resolved: ResolvedRetrieveRequest,
+	inspection: RetrieveInspection,
+	backend: ProtocolAdapter,
+): Promise<string[]> {
+	const availableAttributes = await inspectAttributes(
+		resolved,
+		inspection,
+		backend,
+	);
+	const missing = resolved.attributes.filter(
+		(attribute) => !availableAttributes.includes(attribute),
+	);
+	if (missing.length > 0) {
+		throw new CentrsError({
+			code: "validation/unknown-attribute",
+			summary: `Unknown RouterOS attribute ${missing.join(", ")} for ${resolved.path}.`,
+			remediation:
+				"Check the attribute name, or use `--list-attributes` to inspect the available properties first.",
+			context: {
+				path: resolved.path,
+				parameter: missing[0],
+				requestedAttributes: resolved.attributes,
+				availableAttributes,
+			},
+		});
+	}
+	return availableAttributes;
+}
+
+function queryExpressions(request: RetrieveRequest): string[] {
+	return [request.filter, request.query].flatMap((value) =>
+		value === undefined ? [] : [value].flat(),
+	);
+}
+
+/** Parse `--query`/`--filter` offline; a bad expression fails before any network work. */
+function resolveRetrieveQuery(
+	request: RetrieveRequest,
+): ResolvedRetrieveQuery | undefined {
+	const expressions = queryExpressions(request);
+	if (expressions.length === 0) return undefined;
+	return { expressions, parsed: parseQueries(expressions) };
+}
+
+/**
+ * Validate the predicate's property names against the menu's attributes (the
+ * device fails an unknown one silently: no rows, no trap) and ask it which bare
+ * names are booleans, then compile.
+ */
+async function compileValidatedQuery(
+	resolved: ResolvedRetrieveRequest,
+	query: ResolvedRetrieveQuery,
+	availableAttributes: readonly string[],
+	backend: ProtocolAdapter,
+): Promise<string[]> {
+	const known = new Set([...availableAttributes, ".id"]);
+	const unknown = query.parsed.names.filter((name) => !known.has(name));
+	if (unknown.length > 0) {
+		throw new CentrsError({
+			code: "validation/unknown-attribute",
+			summary: `Unknown RouterOS attribute ${unknown.join(", ")} in --query for ${resolved.path}.`,
+			remediation:
+				"RouterOS answers a query on a misspelled property with no rows, not an error. Check the name with `--list-attributes`.",
+			context: {
+				path: resolved.path,
+				parameter: unknown[0],
+				flag: "--query",
+				query: query.expressions,
+				availableAttributes: [...known].sort(),
+			},
+		});
+	}
+	const booleans = await inspectWhereBooleans(
+		backend,
+		resolved.path,
+		query.parsed.bareNames,
+	);
+	return compileQueryWords(query.parsed, booleans);
+}
+
+/**
+ * `--validate=false` skips inspect, so nothing can say whether a bare name is a
+ * boolean (`disabled=yes`) or "is set"; refuse rather than guess.
+ */
+function compileQueryWithoutValidation(
+	resolved: ResolvedRetrieveRequest,
+): string[] | undefined {
+	const query = resolved.query;
+	if (!query) return undefined;
+	if (isKnownSingletonPath(resolved.path)) {
+		throw singletonQueryError(resolved, query);
+	}
+	if (query.parsed.bareNames.length > 0) {
+		throw new CentrsError({
+			code: "input/invalid-query",
+			summary: `A bare name in --query (${query.parsed.bareNames.join(", ")}) needs validation to learn whether it is a boolean.`,
+			remediation:
+				"Drop `--validate=false`, or write a boolean out as `disabled=yes`.",
+			context: {
+				query: query.expressions,
+				bareNames: query.parsed.bareNames,
+			},
+		});
+	}
+	return compileQueryWords(query.parsed, new Set());
+}
+
+function singletonQueryError(
+	resolved: ResolvedRetrieveRequest,
+	query: ResolvedRetrieveQuery,
+): CentrsError {
+	return new CentrsError({
+		code: "usage/conflicting-flags",
+		summary: `${resolved.path} is a single record, so --query has no rows to filter.`,
+		remediation: `Read it with \`centrs retrieve <router> ${resolved.path}\`, using \`--attribute <name>\` for one value.`,
+		context: { path: resolved.path, flag: "--query", query: query.expressions },
+	});
+}
+
 async function inspectAttributes(
 	resolved: ResolvedRetrieveRequest,
 	inspection: RetrieveInspection,
@@ -1048,13 +1663,15 @@ async function inspectAttributes(
 		.sort();
 }
 
-async function executeRetrieve(
+/** The data half of a read: one `get` (singleton) or `print` (list), projected. */
+export async function executeRetrieve(
 	resolved: ResolvedRetrieveRequest,
 	backend: ProtocolAdapter,
-	inspection: RetrieveInspection | undefined,
+	plan: RetrieveReadPlan,
+	signal?: AbortSignal,
 ): Promise<unknown> {
-	if (inspection?.singleton ?? isKnownSingletonPath(resolved.path)) {
-		const data = await backend.getSingleton(resolved.path);
+	if (plan.inspection?.singleton ?? isKnownSingletonPath(resolved.path)) {
+		const data = await backend.getSingleton(resolved.path, { signal });
 		if (resolved.attributes.length > 0) {
 			return projectSingletonAttributes(data, resolved.attributes);
 		}
@@ -1064,11 +1681,13 @@ async function executeRetrieve(
 	return backend.list(resolved.path, {
 		proplist: resolved.attributes.length > 0 ? resolved.attributes : undefined,
 		detail: resolved.allAttributes,
+		query: plan.query,
+		signal,
 	});
 }
 
 /** Fallback for `--validate=false`, which skips the inspect that detects singletons. */
-function isKnownSingletonPath(path: string): boolean {
+export function isKnownSingletonPath(path: string): boolean {
 	return ["/system/resource", "/system/identity"].includes(
 		path.replace(/\/$/, ""),
 	);