@tikoci/centrs 0.1.7 → 0.1.8

package/src/api.ts

@@ -11,8 +11,8 @@
  * mechanics (id-in-URL vs `=.id=`, `.query` vs `?`-words) live in the adapter.
  *
  * Grounded RouterOS facts this depends on live in `commands/api/AGENTS.md`
- * (CHR 7.23.1). The `--listen` streaming path and multi-target fan-out are later
- * phases; this file is the single-target rest-api + native-api surface.
+ * (CHR 7.23.1 and command-stream examples). Streaming and fan-out reuse this
+ * structured validation, confirmation, and result-envelope surface.
  */
 
 import type {
@@ -27,16 +27,27 @@ import type {
 	ValidationTrace,
 	Warning,
 } from "./core/envelope.ts";
-import { buildTip } from "./core/envelope.ts";
+import { buildTip, notReachedReason } from "./core/envelope.ts";
 import {
 	inspectArgumentNames,
 	inspectChildrenOrEmpty,
+	inspectWhereBooleans,
 	isCommandNode,
 	pathTokens,
 } from "./core/inspect.ts";
+import {
+	compileQueryWords,
+	type ParsedQuery,
+	parseQueries,
+} from "./core/query.ts";
 import { mapRouterOsResultError } from "./core/routeros-errors.ts";
 import { toYaml } from "./core/yaml.ts";
-import { CentrsError, serializeCentrsError } from "./errors.ts";
+import {
+	CentrsError,
+	formatCentrsErrorLine,
+	formatCentrsErrorText,
+	serializeCentrsError,
+} from "./errors.ts";
 import {
 	promptForWriteConfirmation,
 	validateRouterOsScript,
@@ -52,6 +63,7 @@ import {
 	type ProtocolAdapter,
 	type ProtocolApiRequest,
 	type ProtocolApiResult,
+	type ProtocolStreamReply,
 	plannedProtocols,
 	type RouterOsProtocol,
 } from "./protocols/index.ts";
@@ -76,7 +88,7 @@ import {
 	toCoreSource,
 } from "./resolver/index.ts";
 
-export const apiOutputFormats = ["json", "yaml", "text"] as const;
+export const apiOutputFormats = ["json", "ndjson", "yaml", "text"] as const;
 export type ApiOutputFormat = (typeof apiOutputFormats)[number];
 
 /** HTTP methods `api` honors literally against RouterOS's REST verb map. */
@@ -101,7 +113,7 @@ export interface ApiRequest {
 	data?: string;
 	/** `--input` raw JSON body (file/stdin content already read). Mutually exclusive with `fields` / `data`. */
 	inputBody?: string;
-	/** `--query` / `--filter` expressions (`name=value`, `name!=value`, `name>value`, `name`). */
+	/** `--query` / `--filter` expressions, written as after `print where` (`src/core/query.ts`); several are AND-ed. */
 	query?: readonly string[];
 	/** `--raw-query` verbatim RouterOS query words (no leading `?`). */
 	rawQuery?: readonly string[];
@@ -113,11 +125,15 @@ export interface ApiRequest {
 	 * error contract (#154).
 	 */
 	raw?: boolean;
-	/** `--listen`: native-api-only open-ended follow (later phase; rejected here). */
-	listen?: boolean;
-	/** `--duration`: bound a `--listen` stream (later phase). */
+	/**
+	 * `--stream`: deliver the literal command's native replies incrementally.
+	 * It never changes the command: a GET streams one print. To follow changes,
+	 * request the menu's `listen` (`ip/address/listen`), which implies it.
+	 */
+	stream?: boolean;
+	/** `--duration`: bound a native reply stream. */
 	duration?: string;
-	/** `--count`: bound a `--listen` stream to N frames (later phase). */
+	/** `--count`: bound a native reply stream to N rows. */
 	count?: number;
 	via?: string;
 	host?: string;
@@ -160,7 +176,7 @@ export interface NormalizedApiEndpoint {
 	path: string;
 	/** Trailing `*id` segment, when the endpoint addressed one row. */
 	id?: string;
-	/** True when the endpoint's terminal segment was `listen` (infers `--listen`). */
+	/** True when the endpoint's terminal segment was `listen`: the menu's `listen` command, which implies `--stream`. */
 	listen: boolean;
 }
 
@@ -173,7 +189,10 @@ export interface ApiRequestSummary {
 	/** `null` when the method was invalid and no verb could be mapped (error path). */
 	verb: ApiVerb | null;
 	write: boolean;
+	/** The request is the menu's `listen` command (a `/listen` endpoint). */
 	listen: boolean;
+	/** Replies are delivered incrementally (`--stream`, or implied by `listen`). */
+	stream: boolean;
 	yes: boolean;
 	validate: boolean;
 	raw: boolean;
@@ -182,20 +201,41 @@ export interface ApiRequestSummary {
 	proplist?: readonly string[];
 }
 
-/** Why a `--stream` follow ended. */
+/** Why an incremental native command stream ended. */
 export type ApiStreamStopReason =
+	| "completed"
+	| "routeros-error"
 	| "count-reached"
 	| "duration-elapsed"
 	| "interrupted"
 	| "transport-error";
 
-/** Per-line marker on `--stream` NDJSON output: a change frame, or the terminating summary. */
+/**
+ * Per-line marker on `--stream` NDJSON output: a leading `notice`, one wire
+ * reply, or the terminating summary. A `notice` (`data: null`, not counted)
+ * comes first only when the request has advice in `tips` — what RouterOS will
+ * not report for it — so even a watch that never gets a reply sees it. A frame's `reply` is `re` (a row; `data` is the row) or
+ * `empty` (RouterOS `!empty`: zero rows; `data` is `null`). `afterStop` marks a
+ * reply that arrived after centrs stopped the stream locally, such as the
+ * `!empty` a cancelled listen sends; it is not evidence of an empty table.
+ */
 export type ApiStreamMeta =
-	| { kind: "frame"; index: number }
+	| { kind: "notice" }
+	| {
+			kind: "frame";
+			index: number;
+			reply: "re" | "empty";
+			afterStop?: true;
+	  }
 	| {
 			kind: "summary";
 			stopReason: ApiStreamStopReason;
+			/** Every reply line: `rows + empty`. */
 			frames: number;
+			/** `!re` rows. `--count` counts these. */
+			rows: number;
+			/** `!empty` replies. */
+			empty: number;
 			durationMs: number;
 	  };
 
@@ -203,7 +243,11 @@ export type ApiStreamMeta =
 export interface ApiStreamSummary {
 	stopReason: ApiStreamStopReason;
 	frames: number;
+	rows: number;
+	empty: number;
 	durationMs: number;
+	/** Attributes from a received terminal `!done` (for example `ret`). */
+	done?: Record<string, string>;
 }
 
 export interface ApiOperationMeta {
@@ -233,14 +277,25 @@ export interface ResolvedApiRequest {
 	verb: ApiVerb;
 	/** A `/execute` script-run (CLI string, not a path) — inspect gate is not-applicable. */
 	scriptMode: boolean;
+	/** The menu's `listen` command was requested (a `/listen` endpoint). */
 	listen: boolean;
+	/** Deliver replies incrementally (`--stream`, or implied by `listen`). */
+	stream: boolean;
 	/** Resolved JSON body (from `-f` / `-d` / `--input`). */
 	body: Record<string, string>;
-	/** REST `.query` words (no `?` prefix), structured then raw, in order. */
+	/**
+	 * REST `.query` words (no `?` prefix), structured then raw, in order. A bare
+	 * `--query` name reads "is set" here until validation asks the device which
+	 * bare names are booleans ({@link withQueryBooleans}).
+	 */
 	query: readonly string[];
+	/** The parsed `--query` expressions, when any were given. */
+	structuredQuery?: ParsedQuery;
+	/** `--raw-query` words, verbatim. */
+	rawQuery: readonly string[];
 	proplist: readonly string[];
 	raw: boolean;
-	/** `--count`: stop a `--stream` after N frames. */
+	/** `--count`: stop a `--stream` after N `!re` rows (`!empty` does not count). */
 	count?: number;
 	/** `--duration` parsed to ms: stop a `--stream` after this wall-clock window. */
 	durationMs?: number;
@@ -295,10 +350,11 @@ export async function apiEnvelope(
 }
 
 export async function runResolvedApi(
-	resolved: ResolvedApiRequest,
+	request: ResolvedApiRequest,
 	trace: ValidationTrace = {},
 ): Promise<ApiSuccessEnvelope> {
-	assertListenCapability(resolved);
+	let resolved = request;
+	assertStreamCapability(resolved);
 	// Validate the complete request shape before constructing a backend or
 	// running either validation stage. In particular, `/execute` must reject
 	// extra body fields deterministically instead of letting live `:parse`
@@ -320,18 +376,24 @@ export async function runResolvedApi(
 	let validation: EnvelopeValidationMeta;
 	let tips: Tip[] = [];
 	try {
+		// Recorded the moment the gate settles, so a failure in the boolean probe
+		// or the request below reports the gate that passed rather than a guess.
 		if (resolved.validate.value) {
 			const result = await validateApiRequest(resolved, backend, trace);
 			validation = result.validation;
+			trace.validation = validation;
 			tips = result.tips;
+			resolved = await withQueryBooleans(resolved, backend, result.queryMenu);
 		} else {
 			validation = disabledApiValidationMeta(resolved);
+			trace.validation = validation;
 		}
-		// Recorded BEFORE the request, so a transport drop or RouterOS fault below
-		// reports the gate that actually settled rather than a guess.
-		trace.validation = validation;
 
-		const result = await backend.apiRequest(protocolRequest);
+		const result = await backend.apiRequest(
+			resolved === request
+				? protocolRequest
+				: buildProtocolApiRequest(resolved),
+		);
 		const routerOsFailure = apiRouterOsFailureFromResult(resolved, result);
 		if (routerOsFailure) {
 			throw routerOsFailure;
@@ -378,27 +440,29 @@ function apiRouterOsFailureFromResult(
 }
 
 /**
- * The open-ended `--stream` follow path: an async generator yielding one
- * {@link ApiEnvelope} per `/listen` change frame, then a terminating summary
- * envelope (`data` = {@link ApiStreamSummary}). Open-ended follow is native-api
- * only — a `rest-api` (or otherwise unresolved) transport yields a single error
- * envelope. `--count`/`--duration` and `externalSignal` (Ctrl-C) bound it.
- * Errors before the first frame (resolution, validation, confirmation,
- * capability) yield one error envelope and stop — the CLI keys its exit code on
- * that first envelope. `onListening` fires once the follow is established on the
- * wire (a real barrier for callers that must act only after that point).
+ * The `--stream` path: an async generator yielding one {@link ApiEnvelope} per
+ * native reply (`!re` row or `!empty`) to the literal command, then a
+ * terminating summary envelope (`data` = {@link ApiStreamSummary}). It never
+ * rewrites the command; a `<menu>/listen` endpoint is how to follow changes.
+ * Streaming is native-api only — a `rest-api` (or otherwise unresolved)
+ * transport yields a single error envelope. `--count`/`--duration` and
+ * `externalSignal` (Ctrl-C) bound it. Errors before the first frame
+ * (resolution, validation, confirmation, capability) yield one error envelope
+ * and stop — the CLI keys its exit code on that first envelope. `onListening`
+ * fires once the command is on the wire (a real barrier for callers that must
+ * act only after that point).
  */
-export async function* apiListen(
+export async function* apiStream(
 	request: ApiRequest,
 	env: Record<string, string | undefined> = Bun.env,
 	externalSignal?: AbortSignal,
 	onListening?: () => void,
 ): AsyncGenerator<ApiEnvelope, void, void> {
-	// `apiListen` is inherently the streaming surface, so force `listen` on the
-	// request: otherwise a caller that omits it (and the `/listen` endpoint form)
-	// would resolve `via` to the rest-api default and be rejected. An explicit
-	// `--via rest-api` still surfaces capability-unsupported below.
-	const streamRequest: ApiRequest = { ...request, listen: true };
+	// `apiStream` is inherently the streaming surface, so force `stream` on the
+	// request: otherwise a caller that omits it would resolve `via` to the
+	// rest-api default and be rejected. An explicit `--via rest-api` still
+	// surfaces capability-unsupported below.
+	const streamRequest: ApiRequest = { ...request, stream: true };
 	let resolved: ResolvedApiRequest | undefined;
 	try {
 		resolved = await resolveApiRequest(streamRequest, env);
@@ -406,15 +470,16 @@ export async function* apiListen(
 		if (resolved.via.value !== "native-api") {
 			throw new CentrsError({
 				code: "transport/capability-unsupported",
-				summary: "REST cannot follow an open-ended `--stream` (60s cap).",
+				summary: "Incremental `--stream` replies require native-api.",
 				remediation:
-					"Open-ended follow is native-api only: use `--via native-api`, or drop `--stream` for a bounded one-shot.",
-				context: { via: resolved.via.value, capability: "listen" },
+					"Use `--via native-api`, or drop `--stream` for a bounded one-shot response.",
+				context: { via: resolved.via.value, capability: "stream" },
 			});
 		}
 	} catch (error) {
+		// Every failure here comes before stage 1, so an empty trace says so.
 		yield resolved
-			? buildApiErrorEnvelopeFromResolved(resolved, error)
+			? buildApiErrorEnvelopeFromResolved(resolved, error, {})
 			: buildApiErrorEnvelope(streamRequest, error, env);
 		return;
 	}
@@ -422,32 +487,55 @@ export async function* apiListen(
 }
 
 async function* streamResolvedApi(
-	resolved: ResolvedApiRequest,
+	request: ResolvedApiRequest,
 	externalSignal?: AbortSignal,
 	onListening?: () => void,
 ): AsyncGenerator<ApiEnvelope, void, void> {
-	const backend = adapterForResolved(resolved);
+	const backend = adapterForResolved(request);
 
+	let resolved = request;
 	let validation: EnvelopeValidationMeta;
+	const trace: ValidationTrace = {};
 	try {
-		validation = resolved.validate.value
-			? (await validateApiRequest(resolved, backend)).validation
-			: disabledValidationMeta();
+		if (resolved.validate.value) {
+			const result = await validateApiRequest(resolved, backend, trace);
+			validation = result.validation;
+			// The boolean probe below runs after the gate passed (GH#435).
+			trace.validation = validation;
+			resolved = await withQueryBooleans(resolved, backend, result.queryMenu);
+		} else {
+			validation = disabledValidationMeta();
+		}
 	} catch (error) {
 		await backend.close();
-		yield buildApiErrorEnvelopeFromResolved(resolved, error);
+		yield buildApiErrorEnvelopeFromResolved(resolved, error, trace);
 		return;
 	}
 
+	// Request-shape advice is known before the first reply: deliver it first,
+	// and keep it on whichever terminal summary follows (#409 review).
+	const tips = streamTips(resolved);
 	const controller = new AbortController();
 	const startedAt = Date.now();
-	let frames = 0;
+	const counts = { frames: 0, rows: 0, empty: 0 };
 	let stopReason: ApiStreamStopReason | undefined;
 	let cancelUnacknowledged = false;
+	let done: Record<string, string> | undefined;
+	const cancellationWarnings = (): Warning[] =>
+		cancelUnacknowledged
+			? [
+					{
+						code: "transport/cancel-unacknowledged",
+						message: `RouterOS did not acknowledge /cancel within ${resolved.timeoutMs.value}ms; centrs closed the session locally.`,
+						context: { timeoutMs: resolved.timeoutMs.value },
+					},
+				]
+			: [];
 	let durationTimer: ReturnType<typeof setTimeout> | undefined;
 	// The first stop cause wins: the cancel grace window keeps the loop alive
 	// after a stop, so a later timer or frame must not relabel it.
 	const onExternalAbort = (): void => {
+		if (done !== undefined) return;
 		stopReason ??= "interrupted";
 		clearTimeout(durationTimer);
 		controller.abort();
@@ -467,51 +555,69 @@ async function* streamResolvedApi(
 	}
 
 	try {
+		// A consumer may return immediately after this notice; keep it inside
+		// the session cleanup scope, just like every wire reply.
+		if (tips.length > 0) {
+			yield streamNoticeEnvelope(resolved, validation, tips);
+		}
 		const protocolRequest = buildProtocolApiRequest(resolved);
-		for await (const record of backend.listen(protocolRequest, {
+		for await (const reply of backend.stream(protocolRequest, {
 			signal: controller.signal,
 			onListening,
 			onCancelUnacknowledged: () => {
 				cancelUnacknowledged = true;
 			},
+			onDone: (attributes) => {
+				done = attributes;
+				clearTimeout(durationTimer);
+			},
 		})) {
-			frames += 1;
-			yield streamFrameEnvelope(resolved, validation, record, frames);
-			if (resolved.count !== undefined && frames >= resolved.count) {
+			counts.frames += 1;
+			if (reply.type === "empty") counts.empty += 1;
+			else counts.rows += 1;
+			yield streamFrameEnvelope(resolved, validation, reply, counts.frames);
+			// `--count` counts rows only: an empty tick must never use up the
+			// count before the data it is waiting for arrives.
+			if (
+				reply.type === "re" &&
+				resolved.count !== undefined &&
+				counts.rows >= resolved.count
+			) {
 				stopReason ??= "count-reached";
 				break;
 			}
 		}
+		const routerOsFailure = apiRouterOsFailureFromResult(resolved, {
+			data: done?.["ret"],
+		});
+		if (routerOsFailure) throw routerOsFailure;
 		yield streamSummaryEnvelope(
 			resolved,
 			validation,
-			stopReason ?? "interrupted",
-			frames,
+			stopReason ?? "completed",
+			counts,
 			Date.now() - startedAt,
-			cancelUnacknowledged
-				? [
-						{
-							code: "transport/cancel-unacknowledged",
-							message: `RouterOS did not acknowledge /cancel within ${resolved.timeoutMs.value}ms; centrs closed the session locally.`,
-							context: { timeoutMs: resolved.timeoutMs.value },
-						},
-					]
-				: [],
+			tips,
+			cancellationWarnings(),
+			done,
 		);
 	} catch (error) {
-		// A mid-stream failure is itself a frame, tagged `stream.kind="frame"` so
-		// consumers that key off `meta.operation.stream` still see it in the stream
-		// (not as a stray non-stream envelope); the summary then closes with
-		// `transport-error` (the CLI's exit code keys on whether it *started*
-		// cleanly).
-		yield streamErrorFrameEnvelope(resolved, error, frames + 1);
-		yield streamSummaryEnvelope(
-			resolved,
-			validation,
-			"transport-error",
-			frames,
-			Date.now() - startedAt,
-		);
+		const envelope = buildApiErrorEnvelopeFromResolved(resolved, error);
+		envelope.meta.validation = validation;
+		envelope.warnings = [...envelope.warnings, ...cancellationWarnings()];
+		envelope.tips = [...envelope.tips, ...tips];
+		if (envelope.meta.operation) {
+			envelope.meta.operation.stream = {
+				kind: "summary",
+				stopReason: envelope.error.code.startsWith("routeros/")
+					? "routeros-error"
+					: "transport-error",
+				...counts,
+				durationMs: Date.now() - startedAt,
+			};
+			envelope.meta.operation.objectCount = counts.rows;
+		}
+		yield envelope;
 	} finally {
 		if (durationTimer !== undefined) {
 			clearTimeout(durationTimer);
@@ -524,53 +630,114 @@ async function* streamResolvedApi(
 function streamFrameEnvelope(
 	resolved: ResolvedApiRequest,
 	validation: EnvelopeValidationMeta,
-	record: Record<string, unknown>,
+	reply: ProtocolStreamReply,
 	index: number,
 ): ApiSuccessEnvelope {
-	const meta = metaFromResolved(resolved, validation, record);
-	meta.operation.stream = { kind: "frame", index };
-	return { ok: true, data: record, warnings: [], tips: [], meta };
+	const data = reply.type === "empty" ? null : reply.attributes;
+	const meta = metaFromResolved(resolved, validation, data);
+	meta.operation.stream = {
+		kind: "frame",
+		index,
+		reply: reply.type,
+		...(reply.afterStop ? { afterStop: true as const } : {}),
+	};
+	return { ok: true, data, warnings: [], tips: [], meta };
 }
 
-/**
- * A mid-stream failure rendered as a stream frame: the error envelope carries
- * `meta.operation.stream.kind="frame"` (index after the last good frame) so
- * stream consumers can place it on the timeline rather than mistaking it for a
- * non-stream envelope.
- */
-function streamErrorFrameEnvelope(
+function streamNoticeEnvelope(
 	resolved: ResolvedApiRequest,
-	error: unknown,
-	index: number,
-): ApiErrorEnvelope {
-	const envelope = buildApiErrorEnvelopeFromResolved(resolved, error);
-	if (envelope.meta.operation) {
-		envelope.meta.operation.stream = { kind: "frame", index };
-	}
-	return envelope;
+	validation: EnvelopeValidationMeta,
+	tips: Tip[],
+): ApiSuccessEnvelope {
+	const meta = metaFromResolved(resolved, validation, null);
+	meta.operation.stream = { kind: "notice" };
+	return { ok: true, data: null, warnings: [], tips, meta };
 }
 
 function streamSummaryEnvelope(
 	resolved: ResolvedApiRequest,
 	validation: EnvelopeValidationMeta,
 	stopReason: ApiStreamStopReason,
-	frames: number,
+	counts: { frames: number; rows: number; empty: number },
 	durationMs: number,
+	tips: Tip[],
 	streamWarnings: readonly Warning[] = [],
+	done?: Record<string, string>,
 ): ApiSuccessEnvelope {
-	const summary: ApiStreamSummary = { stopReason, frames, durationMs };
+	const summary: ApiStreamSummary = {
+		stopReason,
+		...counts,
+		durationMs,
+		...(done && Object.keys(done).length > 0 ? { done } : {}),
+	};
 	const meta = metaFromResolved(resolved, validation, summary);
-	meta.operation.objectCount = frames;
-	meta.operation.stream = { kind: "summary", stopReason, frames, durationMs };
+	meta.operation.objectCount = counts.rows;
+	meta.operation.stream = {
+		kind: "summary",
+		stopReason,
+		...counts,
+		durationMs,
+	};
 	return {
 		ok: true,
 		data: summary,
 		warnings: [...resolved.warnings, ...streamWarnings],
-		tips: [],
+		tips,
 		meta,
 	};
 }
 
+/**
+ * `api` sends the command as typed, so what RouterOS will not report is said
+ * as a tip, not fixed by rewriting the request (#396 decisions). Grounded on
+ * CHR 7.23.7 + 7.24.5: a GET stream is one finite print; a filtered change feed
+ * drops rows leaving the filter and every delete except under an `?.id=`
+ * query; a `.proplist` without `.id,.dead` strips both from a delete frame,
+ * even under `?.id=` (it arrives as an `!re` with no attributes).
+ */
+function streamTips(resolved: ResolvedApiRequest): Tip[] {
+	const tips: Tip[] = [];
+	const menu = resolved.id ? `${resolved.path}/${resolved.id}` : resolved.path;
+	if (resolved.verb === "print" && !resolved.listen) {
+		tips.push(
+			buildTip(
+				"tip/stream-print",
+				`GET ${menu} --stream streamed one print; it does not follow changes.`,
+				`To follow changes, request the menu's listen: \`centrs api <router> ${menu}/listen\` (or POST \`${resolved.path}/print -f follow-only=${resolved.id ? ` --query .id=${resolved.id}` : ""}\`).`,
+			),
+		);
+	}
+	const follows =
+		resolved.listen ||
+		"follow-only" in resolved.body ||
+		"follow" in resolved.body;
+	if (!follows) return tips;
+	const filtered = resolved.query.some((word) => !word.startsWith(".id="));
+	if (filtered) {
+		tips.push(
+			buildTip(
+				"tip/filtered-follow",
+				"RouterOS ran this change feed with a query, so it reports neither rows that leave the filter nor deletes.",
+				"Follow the unfiltered menu and filter on the client, or address one row (`<menu>/*id/listen`), whose delete is reported.",
+			),
+		);
+	}
+	const projection = resolved.proplist;
+	if (
+		projection.length > 0 &&
+		!(projection.includes(".id") && projection.includes(".dead"))
+	) {
+		tips.push(
+			buildTip(
+				"tip/follow-proplist",
+				"This --proplist omits `.id` or `.dead`, which RouterOS then strips from delete frames: a delete can arrive as a row with no attributes.",
+				"Add `.id,.dead` to --proplist to see deletes.",
+			),
+		);
+	}
+	return tips;
+}
+
 function adapterForResolved(resolved: ResolvedApiRequest): ProtocolAdapter {
 	return createProtocolAdapter({
 		protocol: resolved.via.value,
@@ -616,7 +783,9 @@ export async function resolveApiRequest(
 	const normalized = normalizeApiEndpoint(request.endpoint);
 	const method = parseApiMethod(request.method);
 	const verb = mapMethodToVerb(method);
-	const listen = (request.listen ?? false) || normalized.listen;
+	const listen = normalized.listen;
+	// A listen never completes, so it is only ever streamed.
+	const stream = (request.stream ?? false) || listen;
 	// `/execute` (root, single token) run via POST is the script surface — a CLI
 	// string, not a menu path. A GET, a nested path, or any other menu that merely
 	// ends in `execute` stays a normal path request validated through inspect.
@@ -635,10 +804,59 @@ export async function resolveApiRequest(
 			context: { method, path: normalized.path },
 		});
 	}
+	// PUT/POST map no row id onto the wire: native would drop it silently and
+	// REST would fold it into `.query`, so the transports would disagree.
+	if ((verb === "add" || verb === "run") && normalized.id !== undefined) {
+		throw new CentrsError({
+			code: "input/invalid-path",
+			summary: `A ${method} request does not address a row by id (${normalized.id}).`,
+			remediation:
+				"Drop the trailing id; use PATCH/DELETE for one row, or pass `.id` as a command field such as `-f .id=*1`.",
+			context: { method, path: normalized.path, id: normalized.id },
+		});
+	}
 	const raw = request.raw ?? false;
 	const body = buildApiBody(request);
-	const query = buildApiQuery(request);
+	const structuredQuery =
+		(request.query?.length ?? 0) > 0
+			? parseQueries(request.query ?? [])
+			: undefined;
+	const rawQuery = [...(request.rawQuery ?? [])];
+	const query = [
+		...(structuredQuery ? compileQueryWords(structuredQuery, new Set()) : []),
+		...rawQuery,
+	];
 	const proplist = buildApiProplist(request);
+	if (
+		((verb !== "print" && verb !== "run") || scriptMode) &&
+		(query.length > 0 || proplist.length > 0)
+	) {
+		throw new CentrsError({
+			code: "usage/conflicting-flags",
+			summary:
+				"Query and projection flags require a GET or a structured POST command.",
+			remediation:
+				"Remove --query/--raw-query/--proplist from mutation and script requests; address PATCH/DELETE by row id.",
+		});
+	}
+	if (listen && method !== "GET") {
+		throw new CentrsError({
+			code: "usage/conflicting-flags",
+			summary: "An explicit /listen endpoint requires GET.",
+			remediation:
+				"Drop -X to follow that menu, or POST the menu's print with `-f follow-only=` to pass print arguments.",
+		});
+	}
+	// A GET maps to print, which takes no body here; refuse the fields rather
+	// than drop them from a stream.
+	if (stream && verb === "print" && Object.keys(body).length > 0) {
+		throw new CentrsError({
+			code: "usage/conflicting-flags",
+			summary: "A streamed GET does not accept command fields.",
+			remediation:
+				"Use -X POST with the full command path to stream command attributes, such as /system/resource/print -f interval=1.",
+		});
+	}
 
 	// A quickchr target is a named-live-provider: host/port/auth come from the
 	// live descriptor, bypassing CDB, `__default__`, and MAC resolution.
@@ -661,7 +879,7 @@ export async function resolveApiRequest(
 				env,
 				config,
 			)));
-	const via = resolveApiProtocol(request, env, listen, cdbResolution, config);
+	const via = resolveApiProtocol(request, env, stream, cdbResolution, config);
 	const format = resolveApiFormat(request, env, config);
 	// `--raw` is a PRECEDENCE LAYER, not an override (#154). It ranks below an
 	// explicit `--validate` and above every ambient source, so:
@@ -697,6 +915,19 @@ export async function resolveApiRequest(
 					cdbResolution?.overrides.validate,
 					config,
 				);
+	if (!validate.value && (structuredQuery?.bareNames.length ?? 0) > 0) {
+		throw new CentrsError({
+			code: "input/invalid-query",
+			summary: `A bare name in --query (${structuredQuery?.bareNames.join(", ")}) needs validation to learn whether it is a boolean.`,
+			remediation:
+				'Drop `--validate=false`/`--raw`, or spell the word out: `--query disabled=yes` for a boolean, `--raw-query comment` for "is set".',
+			context: {
+				query: request.query,
+				bareNames: structuredQuery?.bareNames,
+				validate: validate.source,
+			},
+		});
+	}
 	const timeoutMs = resolveApiTimeout(
 		request.timeout,
 		env,
@@ -777,8 +1008,11 @@ export async function resolveApiRequest(
 		verb,
 		scriptMode,
 		listen,
+		stream,
 		body,
 		query,
+		structuredQuery,
+		rawQuery,
 		proplist,
 		raw,
 		count: request.count,
@@ -917,38 +1151,36 @@ function parseJsonBody(raw: string, flag: string): Record<string, string> {
 }
 
 /**
- * Build REST `.query` words (no `?` prefix). Structured `--query` words first, in
- * order, then verbatim `--raw-query` words. Mapping is CHR-grounded
- * (`commands/api/AGENTS.md`): `name=value` (eq), `name!=value` → `name=value`,
- * `#!` (eq then NOT-top), `name>value`/`name<value` → `>name=value`/`<name=value`,
- * bare `name` (has-property).
+ * REST `.query` words (no `?` prefix) for a request summary: structured
+ * `--query` words first (`src/core/query.ts`, bare names as "is set"), then
+ * verbatim `--raw-query` words. Throws `input/invalid-query` on a bad
+ * expression.
  */
 export function buildApiQuery(request: ApiRequest): string[] {
-	const words: string[] = [];
-	for (const expression of request.query ?? []) {
-		words.push(...queryExpressionToWords(expression));
-	}
-	for (const raw of request.rawQuery ?? []) {
-		words.push(raw);
-	}
-	return words;
+	const structured =
+		(request.query?.length ?? 0) > 0
+			? compileQueryWords(parseQueries(request.query ?? []), new Set())
+			: [];
+	return [...structured, ...(request.rawQuery ?? [])];
 }
 
-function queryExpressionToWords(expression: string): string[] {
-	const ne = expression.indexOf("!=");
-	if (ne >= 0) {
-		return [`${expression.slice(0, ne)}=${expression.slice(ne + 2)}`, "#!"];
-	}
-	const gt = expression.indexOf(">");
-	if (gt >= 0) {
-		return [`>${expression.slice(0, gt)}=${expression.slice(gt + 1)}`];
-	}
-	const lt = expression.indexOf("<");
-	if (lt >= 0) {
-		return [`<${expression.slice(0, lt)}=${expression.slice(lt + 1)}`];
-	}
-	// `name=value` (eq) or bare `name` (has-property) pass through verbatim.
-	return [expression];
+/**
+ * The resolved request with its `--query` bare names compiled by type: the
+ * device says which are booleans (`disabled` → `disabled=yes`); the rest mean
+ * "is set". Unchanged when there are no bare names.
+ */
+export async function withQueryBooleans(
+	resolved: ResolvedApiRequest,
+	backend: ProtocolAdapter,
+	menu: string,
+): Promise<ResolvedApiRequest> {
+	const parsed = resolved.structuredQuery;
+	if (!parsed || parsed.bareNames.length === 0) return resolved;
+	const booleans = await inspectWhereBooleans(backend, menu, parsed.bareNames);
+	return {
+		...resolved,
+		query: [...compileQueryWords(parsed, booleans), ...resolved.rawQuery],
+	};
 }
 
 function buildApiProplist(request: ApiRequest): string[] {
@@ -974,6 +1206,9 @@ export function buildProtocolApiRequest(
 	if (resolved.id) {
 		request.id = resolved.id;
 	}
+	if (resolved.listen) {
+		request.listen = true;
+	}
 	if (resolved.scriptMode) {
 		const { script, ...extra } = resolved.body;
 		if (typeof script !== "string" || script.trim().length === 0) {
@@ -1005,7 +1240,7 @@ export function buildProtocolApiRequest(
 			request.attributes = resolved.body;
 		}
 	}
-	if (resolved.verb === "print") {
+	if (resolved.verb === "print" || resolved.verb === "run") {
 		if (resolved.query.length > 0) {
 			request.query = resolved.query;
 		}
@@ -1023,6 +1258,8 @@ const API_SCRIPT_DEVICE_STAGE_SOURCE = ":put [:parse]";
 interface ApiValidationResult {
 	validation: EnvelopeValidationMeta;
 	tips: Tip[];
+	/** The menu a `--query` bare name is probed in: the path's parent only when inspect confirmed its last segment is a command. */
+	queryMenu: string;
 }
 
 /**
@@ -1086,6 +1323,7 @@ async function validateApiRequest(
 				],
 			},
 			tips: [],
+			queryMenu: resolved.path,
 		};
 	}
 
@@ -1158,6 +1396,7 @@ async function validateApiRequest(
 				semantic: true,
 			},
 			tips,
+			queryMenu: isCommand ? `/${parent.join("/")}` : resolved.path,
 		};
 	}
 
@@ -1202,6 +1441,7 @@ async function validateApiRequest(
 				availableAttributes: available,
 			},
 			tips,
+			queryMenu: resolved.path,
 		};
 	}
 
@@ -1214,6 +1454,7 @@ async function validateApiRequest(
 			semantic: true,
 		},
 		tips,
+		queryMenu: resolved.path,
 	};
 }
 
@@ -1275,38 +1516,39 @@ async function assertApiWriteConfirmed(
 	});
 }
 
-function assertListenCapability(resolved: ResolvedApiRequest): void {
-	if (!resolved.listen) {
+function assertStreamCapability(resolved: ResolvedApiRequest): void {
+	if (!resolved.stream) {
 		return;
 	}
 	if (resolved.via.value === "rest-api") {
 		throw new CentrsError({
 			code: "transport/capability-unsupported",
-			summary: "REST cannot follow an open-ended `--stream` (60s cap).",
+			summary: "Incremental `--stream` replies require native-api.",
 			remediation:
-				"Open-ended follow is native-api only: use `--via native-api`, or drop `--stream` for a bounded one-shot.",
-			context: { via: resolved.via.value, capability: "listen" },
+				"Use `--via native-api`, or drop `--stream` for a bounded one-shot response.",
+			context: { via: resolved.via.value, capability: "stream" },
 		});
 	}
 	throw new CentrsError({
 		code: "input/invalid-command",
-		summary: "`--stream` is an open-ended follow, not a one-shot `api` call.",
+		summary:
+			"`--stream` yields incremental replies instead of a one-shot `api` result.",
 		remediation:
-			"Consume the stream via `apiListen()` (library) or `centrs api … --stream` (CLI); both yield an NDJSON envelope per change frame plus a final summary.",
-		context: { via: resolved.via.value, capability: "listen" },
+			"Consume the stream via `apiStream()` (library) or `centrs api … --stream` (CLI); both yield an NDJSON envelope per reply frame plus a final summary.",
+		context: { via: resolved.via.value, capability: "stream" },
 	});
 }
 
 function resolveApiProtocol(
 	request: ApiRequest,
 	env: Record<string, string | undefined>,
-	listen: boolean,
+	stream: boolean,
 	cdb?: CdbResolution,
 	config: Record<string, string | undefined> = {},
 ): ResolvedSetting<RouterOsProtocol> {
-	// A `/listen` endpoint (or `--listen`) infers native-api when `--via` is unset;
-	// REST stays the default for one-shot calls.
-	const defaultVia: RouterOsProtocol = listen ? "native-api" : "rest-api";
+	// A stream (`--stream` or a `/listen` endpoint) infers native-api when
+	// `--via` is unset; REST stays the default for one-shot calls.
+	const defaultVia: RouterOsProtocol = stream ? "native-api" : "rest-api";
 	const via = resolveStringSetting(
 		request.via,
 		env,
@@ -1450,7 +1692,9 @@ export function buildApiErrorEnvelope(
 					write: parsedMethod
 						? isApiMutating(parsedMethod, reportedPath)
 						: false,
-					listen: request.listen ?? false,
+					listen: safeNormalizeListen(request.endpoint),
+					stream:
+						(request.stream ?? false) || safeNormalizeListen(request.endpoint),
 					yes: request.yes ?? false,
 					validate: summarizedValidate(request),
 					raw: request.raw ?? false,
@@ -1515,25 +1759,50 @@ function failedApiValidationMeta(
 			],
 		};
 	}
-	// `stages` is only asserted when a `validation/*` error identifies the device
-	// stage as the rejecter. Everything downstream — a RouterOS fault on the
-	// request, a transport drop — passed the gate and is served by
-	// `trace.validation` before this function is ever reached.
-	const deviceRejected = error.code.startsWith("validation/");
+	// Only a `validation/*` error identifies the device stage as the rejecter.
+	// Everything downstream of a passed gate — a RouterOS fault on the request,
+	// a transport drop — is served by `trace.validation` before this function is
+	// ever reached.
+	if (error.code.startsWith("validation/")) {
+		return {
+			enabled: true,
+			source: apiDeviceStageSource(resolved),
+			result: "failed",
+			syntax: false,
+			semantic: resolved.scriptMode ? "not-applicable" : false,
+			stages: [offlineApiStage(resolved, trace), deviceStageFailed(resolved)],
+		};
+	}
+	// Anything else stopped the gate before it produced a verdict: a transport or
+	// auth failure, a device error that is not a gate answer, or a refusal before
+	// the gate ran (write confirmation, a non-native `--stream`). No `result`, no
+	// `syntax` / `semantic` — no stage said either (GH#435). Without a trace a
+	// script request cannot say whether stage 1 ran, so that stage is left out.
+	const reason = notReachedReason(error.code);
+	const source = apiDeviceStageSource(resolved);
+	const device: EnvelopeValidationStage = {
+		stage: "device",
+		source,
+		result: "skipped",
+		reason,
+	};
+	if (resolved.scriptMode && !trace) {
+		return { enabled: true, source, stages: [device] };
+	}
 	return {
 		enabled: true,
-		source: apiDeviceStageSource(resolved),
-		result: "failed",
-		syntax: false,
-		semantic: resolved.scriptMode ? "not-applicable" : false,
-		...(deviceRejected
-			? {
-					stages: [
-						offlineApiStage(resolved, trace),
-						deviceStageFailed(resolved),
-					],
-				}
-			: {}),
+		source,
+		stages: [
+			resolved.scriptMode && trace?.offlineVerdict === undefined
+				? {
+						stage: "offline",
+						source: OFFLINE_GATE_SOURCE,
+						result: "skipped",
+						reason,
+					}
+				: offlineApiStage(resolved, trace),
+			device,
+		],
 	};
 }
 
@@ -1635,12 +1904,16 @@ export function renderApiEnvelope(
 	switch (format) {
 		case "json":
 			return JSON.stringify(envelope, null, 2);
+		// One envelope, one compact line: the same line shape as a stream, so a
+		// one-shot read and a `--stream` are both read line by line.
+		case "ndjson":
+			return JSON.stringify(envelope);
 		case "yaml":
 			return toYaml(envelope);
 		case "text":
 			return envelope.ok
 				? renderApiSuccessText(envelope, options)
-				: renderApiErrorText(envelope, options);
+				: formatCentrsErrorText(envelope.error, options);
 		default:
 			return exhaustiveFormat(format);
 	}
@@ -1670,20 +1943,27 @@ export function renderApiStreamLine(
 		}
 		// A streamed error must stay one line too — never the verbose blank-line +
 		// pretty-printed context block that `renderApiErrorText` emits.
-		const error = envelope.error;
-		return error.remediation
-			? `[${error.code}] ${error.summary} — Fix: ${error.remediation}`
-			: `[${error.code}] ${error.summary}`;
+		return formatCentrsErrorLine(envelope.error);
 	}
-	// json and yaml both stream as NDJSON: one compact envelope object per line.
-	// (yaml falls back to JSON — a multi-line YAML doc can't be one stream line.)
+	// ndjson, json and yaml all stream as NDJSON: one compact envelope object
+	// per line. (json keeps this for compatibility; yaml falls back to JSON — a
+	// multi-line YAML doc can't be one stream line.)
 	return JSON.stringify(envelope);
 }
 
 function renderApiStreamFrameText(envelope: ApiSuccessEnvelope): string {
 	const stream = envelope.meta.operation?.stream;
 	if (stream?.kind === "summary") {
-		return `— ${stream.stopReason}: ${stream.frames} frame(s) in ${stream.durationMs}ms`;
+		const empty = stream.empty > 0 ? `, ${stream.empty} empty` : "";
+		return `— ${stream.stopReason}: ${stream.rows} row(s)${empty} in ${stream.durationMs}ms`;
+	}
+	if (stream?.kind === "notice") {
+		return envelope.tips
+			.map((tip) => `tip: ${tip.message}${tip.fix ? ` ${tip.fix}` : ""}`)
+			.join("\n");
+	}
+	if (stream?.kind === "frame" && stream.reply === "empty") {
+		return `${stream.index}\t!empty`;
 	}
 	const index = stream?.kind === "frame" ? stream.index : 0;
 	return `${index}\t${JSON.stringify(envelope.data)}`;
@@ -1725,21 +2005,12 @@ function renderApiSuccessText(
 	return lines.join("\n");
 }
 
-function renderApiErrorText(
-	envelope: ApiErrorEnvelope,
-	options: { verbose?: boolean },
-): string {
-	const lines = [`[${envelope.error.code}] ${envelope.error.summary}`];
-	if (envelope.error.remediation) {
-		lines.push(`Fix: ${envelope.error.remediation}`);
-	}
-	if (options.verbose && envelope.error.context) {
-		lines.push("", JSON.stringify(envelope.error.context, null, 2));
-	}
-	return lines.join("\n");
-}
-
 export function validateApiRequestShape(request: ApiRequest): void {
+	// `listen` used to mean "stream" AND rewrote a GET into a change feed (#402).
+	// Refuse it rather than let an untyped caller silently get a finite print.
+	if ("listen" in request) {
+		throw removedListenError(request.endpoint, "library");
+	}
 	if (!request.endpoint || request.endpoint.trim().length === 0) {
 		throw new CentrsError({
 			code: "input/invalid-command",
@@ -1759,6 +2030,31 @@ export function validateApiRequestShape(request: ApiRequest): void {
 	}
 }
 
+/**
+ * `--listen` / `ApiRequest.listen` were removed in #402: they meant "stream"
+ * and also turned a GET into a change feed, which a literal `api` must not do.
+ * The error names the exact replacement instead of guessing which was meant.
+ */
+export function removedListenError(
+	endpoint: string,
+	surface: "cli" | "library",
+	replacement?: string,
+): CentrsError {
+	const menu = safeNormalizeMenu(endpoint);
+	return new CentrsError({
+		code: "usage/removed-flag",
+		summary:
+			surface === "cli"
+				? "`--listen` was removed: `api` no longer rewrites a request into a listen."
+				: "`ApiRequest.listen` was removed: `api` no longer rewrites a request into a listen.",
+		remediation:
+			surface === "cli"
+				? `Run: ${replacement ?? `centrs api <router> ${menu}/listen`}${replacement?.includes("<") ? " (fill each <placeholder> in from your command)" : ""}. A \`/listen\` endpoint follows changes; \`--stream\` streams any other command as typed.`
+				: `To follow changes, use \`apiStream()\` with endpoint \`${menu}/listen\`; to stream another command as typed, set \`stream: true\`.`,
+		context: { flag: surface === "cli" ? "--listen" : "listen", endpoint },
+	});
+}
+
 export function parseApiMethod(method: string | undefined): ApiMethod {
 	if (method === undefined) {
 		return "GET";
@@ -1786,7 +2082,7 @@ export function apiRequestSummaryFromRequest(
 ): ApiRequestSummary {
 	const normalized = normalizeApiEndpoint(request.endpoint);
 	const parsed = tryParseApiMethod(request.method);
-	const listen = (request.listen ?? false) || normalized.listen;
+	const listen = normalized.listen;
 	return {
 		endpoint: request.endpoint,
 		path: normalized.path,
@@ -1795,15 +2091,25 @@ export function apiRequestSummaryFromRequest(
 		verb: parsed ? mapMethodToVerb(parsed) : null,
 		write: parsed ? isApiMutating(parsed, normalized.path) : false,
 		listen,
+		stream: (request.stream ?? false) || listen,
 		yes: request.yes ?? false,
 		validate: summarizedValidate(request),
 		raw: request.raw ?? false,
 		format: resolveErrorFormat(request, env),
-		query: buildApiQuery(request),
+		query: summaryQuery(request),
 		proplist: buildApiProplist(request),
 	};
 }
 
+/** {@link buildApiQuery} for an error summary, which must not throw on the expression it reports. */
+function summaryQuery(request: ApiRequest): string[] | undefined {
+	try {
+		return buildApiQuery(request);
+	} catch {
+		return undefined;
+	}
+}
+
 /** Parse a method without throwing: a valid {@link ApiMethod}, or `undefined` when invalid. */
 function tryParseApiMethod(method: string | undefined): ApiMethod | undefined {
 	if (method === undefined) {
@@ -1815,6 +2121,24 @@ function tryParseApiMethod(method: string | undefined): ApiMethod | undefined {
 		: undefined;
 }
 
+/** The endpoint's path plus any row id (`/ip/address/*1`), without a `/listen`. */
+function safeNormalizeMenu(endpoint: string): string {
+	try {
+		const { path, id } = normalizeApiEndpoint(endpoint);
+		return id ? `${path}/${id}` : path;
+	} catch {
+		return endpoint;
+	}
+}
+
+function safeNormalizeListen(endpoint: string): boolean {
+	try {
+		return normalizeApiEndpoint(endpoint).listen;
+	} catch {
+		return false;
+	}
+}
+
 function safeNormalizePath(endpoint: string): string {
 	try {
 		return normalizeApiEndpoint(endpoint).path;
@@ -1910,6 +2234,7 @@ function apiRequestSummary(resolved: ResolvedApiRequest): ApiRequestSummary {
 		verb: resolved.verb,
 		write: isApiMutating(resolved.method, resolved.path),
 		listen: resolved.listen,
+		stream: resolved.stream,
 		yes: resolved.yes,
 		validate: resolved.validate.value,
 		raw: resolved.raw,