@tikoci/centrs 0.1.3 → 0.1.6

package/src/execute.ts

@@ -5,19 +5,28 @@ import type {
 	CommonSettingsMeta,
 	SettingSource as CoreSettingSource,
 	EnvelopeValidationMeta,
+	EnvelopeValidationStage,
 	Tip,
+	ValidationTrace,
 	Warning,
 } from "./core/envelope.ts";
 import { buildTip } from "./core/envelope.ts";
 import {
-	extractCompletionNames,
-	inspectChildren,
-	inspectCompletions,
-	isArgumentNode,
-	pathTokens,
-} from "./core/inspect.ts";
+	type CanonicalExecuteCommand,
+	canonicalizeExecuteCommand,
+	isWriteShaped,
+} from "./core/execute-command.ts";
+import { inspectArgumentNames, pathTokens } from "./core/inspect.ts";
 import { mapRouterOsError } from "./core/routeros-errors.ts";
+import { routerOsStringLiteral } from "./core/routeros-string.ts";
+import { toYaml } from "./core/yaml.ts";
 import { CentrsError, serializeCentrsError } from "./errors.ts";
+import {
+	assertOfflineSyntax,
+	isOfflineGateRejection,
+	OFFLINE_GATE_SOURCE,
+	type OfflineGateResult,
+} from "./offline-gate.ts";
 import {
 	createProtocolAdapter,
 	getProtocolPlan,
@@ -31,6 +40,7 @@ import {
 	parseScriptFor,
 } from "./protocols/mac-telnet-console.ts";
 import {
+	assertNoQuickchrOverrideConflict,
 	type CdbResolution,
 	effectiveHostCandidate,
 	isIpTransport,
@@ -38,6 +48,7 @@ import {
 	loadEnvFileDefaults,
 	parseDuration,
 	parseResolvePolicy,
+	quickchrConnection,
 	type ResolvedAuth,
 	type ResolvedSetting,
 	type ResolvedTarget,
@@ -46,17 +57,23 @@ import {
 	resolveCdb,
 	resolveMacTarget,
 	resolveOptionalIntegerSetting,
+	resolveQuickchrTarget,
 	resolveStringSetting,
 	resolveTarget,
 	toCoreSource,
 } from "./resolver/index.ts";
-import { toYaml } from "./retrieve.ts";
 
 export const executeOutputFormats = ["text", "json", "yaml"] as const;
 export type ExecuteOutputFormat = (typeof executeOutputFormats)[number];
 
 export interface ExecuteRequest {
 	targetInput?: string;
+	/**
+	 * quickchr machine name (`--quickchr <name>`): resolve host/port/auth from
+	 * the live VM descriptor instead of CDB/env (`docs/CONSTITUTION.md` →
+	 * Resolution providers). Conflicts with host/port/username/password/sshKey.
+	 */
+	quickchr?: string;
 	command: string;
 	via?: string;
 	host?: string;
@@ -115,14 +132,17 @@ export type ExecuteSuccessEnvelope = CentrsSuccessEnvelope<
 >;
 export type ExecuteErrorEnvelope = CentrsErrorEnvelope<ExecuteOperationMeta>;
 
-export interface CanonicalExecuteCommand {
-	mode: "structured" | "script";
-	input: string;
-	path: string;
-	verb: string;
-	attributes: Record<string, string>;
-	queries: string[];
-}
+/**
+ * The execution gate itself lives in `src/core/execute-command.ts` (pure, no
+ * transport reach) and is re-exported here because this module is its
+ * documented public home — `src/index.ts`, `src/mcp/tools.ts` and the locked
+ * contract table all import it from `execute` (#312).
+ */
+export {
+	type CanonicalExecuteCommand,
+	canonicalizeExecuteCommand,
+	isWriteShaped,
+};
 
 export interface ResolvedExecuteRequest {
 	command: string;
@@ -162,13 +182,23 @@ export async function executeEnvelope(
 	env: Record<string, string | undefined> = Bun.env,
 ): Promise<ExecuteEnvelope> {
 	let resolved: ResolvedExecuteRequest | undefined;
+	// The gate finishes inside `runResolvedExecute`, but the error envelope is
+	// built out here after the throw has unwound past it. Without the trace, a
+	// RouterOS fault on the *run* — both stages already green — reported a
+	// reconstructed `result: "failed"` that erased the real outcome.
+	const trace: ValidationTrace = {};
 	try {
 		resolved = await resolveExecuteRequest(request, env);
 		await assertWriteConfirmed(request, resolved);
-		return await runResolvedExecute(resolved);
+		return await runResolvedExecute(resolved, trace);
 	} catch (error) {
 		return resolved
-			? buildExecuteErrorEnvelopeFromResolved(resolved, error)
+			? buildExecuteErrorEnvelopeFromResolved(
+					resolved,
+					error,
+					trace.validation,
+					trace,
+				)
 			: buildExecuteErrorEnvelope(request, error, env);
 	}
 }
@@ -186,6 +216,7 @@ export async function validateExecuteEnvelope(
 	env: Record<string, string | undefined> = Bun.env,
 ): Promise<ExecuteEnvelope> {
 	let resolved: ResolvedExecuteRequest | undefined;
+	const trace: ValidationTrace = {};
 	try {
 		resolved = await resolveExecuteRequest({ ...request, validate: true }, env);
 		const backend = createProtocolAdapter({
@@ -202,7 +233,7 @@ export async function validateExecuteEnvelope(
 			insecure: resolved.insecure.value,
 		});
 		try {
-			const validation = await validateExecuteCommand(resolved, backend);
+			const validation = await validateExecuteCommand(resolved, backend, trace);
 			return {
 				ok: true,
 				data: null,
@@ -215,13 +246,14 @@ export async function validateExecuteEnvelope(
 		}
 	} catch (error) {
 		return resolved
-			? buildExecuteErrorEnvelopeFromResolved(resolved, error)
+			? buildExecuteErrorEnvelopeFromResolved(resolved, error, undefined, trace)
 			: buildExecuteErrorEnvelope(request, error, env);
 	}
 }
 
 export async function runResolvedExecute(
 	resolved: ResolvedExecuteRequest,
+	trace: ValidationTrace = {},
 ): Promise<ExecuteSuccessEnvelope> {
 	const backend = createProtocolAdapter({
 		protocol: resolved.via.value,
@@ -243,16 +275,13 @@ export async function runResolvedExecute(
 
 	try {
 		if (resolved.validate.value) {
-			validation = await validateExecuteCommand(resolved, backend);
+			validation = await validateExecuteCommand(resolved, backend, trace);
 		} else {
-			validation = {
-				enabled: false,
-				source: "disabled",
-				result: "skipped",
-				syntax: false,
-				semantic: false,
-			};
+			validation = disabledValidationMeta();
 		}
+		// Recorded BEFORE the run, so a RouterOS fault or transport drop below
+		// reports the gate that actually passed rather than a guess.
+		trace.validation = validation;
 
 		const result = await runCommand(resolved, backend);
 		const routerOsFailure = routerOsFailureFromResult(
@@ -286,19 +315,30 @@ export async function resolveExecuteRequest(
 	validateExecuteRequestShape(request);
 	const canonical = canonicalizeExecuteCommand(request.command);
 	const config = options.config ?? (await loadEnvFileDefaults(env));
+	// A quickchr target is a named-live-provider: it supplies host/port/auth from
+	// the live descriptor and bypasses CDB/env resolution for those fields
+	// entirely (no CDB load, no `__default__` ladder, no MAC resolution).
+	let quickchrResolution: Awaited<
+		ReturnType<typeof resolveQuickchrTarget>
+	> | null = null;
+	if (request.quickchr !== undefined) {
+		assertNoQuickchrOverrideConflict(request, request.quickchr);
+		quickchrResolution = await resolveQuickchrTarget(request.quickchr);
+	}
 	// Fan-out passes the pre-resolved CDB record for a member (the CDB is loaded
-	// once in `expandCdbSelection`); single-target resolves it here.
-	const cdbResolution =
-		options.cdbResolution ??
-		(await resolveCdb(
-			{
-				targetInput: request.targetInput,
-				cdbFile: request.cdbFile,
-				cdbPassword: request.cdbPassword,
-			},
-			env,
-			config,
-		));
+	// once in `expandSelection`); single-target resolves it here.
+	const cdbResolution = quickchrResolution
+		? undefined
+		: (options.cdbResolution ??
+			(await resolveCdb(
+				{
+					targetInput: request.targetInput,
+					cdbFile: request.cdbFile,
+					cdbPassword: request.cdbPassword,
+				},
+				env,
+				config,
+			)));
 	const via = resolveExecuteProtocol(request, env, cdbResolution, config);
 	const format = resolveFormat(request, env, config);
 	const validate = resolveBooleanSetting(
@@ -325,50 +365,72 @@ export async function resolveExecuteRequest(
 		undefined,
 		config,
 	);
-	const macResolution = isIpTransport(via.value)
-		? await resolveMacTarget({
-				host: request.host,
-				targetInput: request.targetInput,
-				cdbTarget: cdbResolution?.target,
+	const macResolution =
+		quickchrResolution === null && isIpTransport(via.value)
+			? await resolveMacTarget({
+					host: request.host,
+					targetInput: request.targetInput,
+					cdbTarget: cdbResolution?.target,
+					env,
+					config,
+					policy: parseResolvePolicy(
+						request.resolve ??
+							env["CENTRS_RESOLVE"] ??
+							config["CENTRS_RESOLVE"],
+					),
+					operation: "execute",
+				})
+			: undefined;
+	const connection = quickchrResolution
+		? quickchrConnection(quickchrResolution, via.value)
+		: null;
+	const target = connection
+		? connection.target
+		: resolveTarget(
+				{
+					targetInput: request.targetInput,
+					host: request.host,
+					port: request.port,
+					macResolution,
+				},
 				env,
+				via.value,
+				cdbResolution,
 				config,
-				policy: parseResolvePolicy(
-					request.resolve ?? env["CENTRS_RESOLVE"] ?? config["CENTRS_RESOLVE"],
-				),
-				operation: "execute",
-			})
-		: undefined;
-	const target = resolveTarget(
-		{
-			targetInput: request.targetInput,
-			host: request.host,
-			port: request.port,
-			macResolution,
-		},
-		env,
-		via.value,
-		cdbResolution,
-		config,
-	);
-	const auth = resolveAuth(
-		{
-			username: request.username,
-			password: request.password,
-			sshKey: request.sshKey,
-		},
-		env,
-		cdbResolution,
-		config,
-	);
-	const insecure = resolveBooleanSetting(
-		request.insecure,
-		env,
-		"CENTRS_INSECURE",
-		false,
-		"insecure",
-		cdbResolution?.overrides.insecure,
-		config,
-	);
+			);
+	const auth = connection
+		? connection.auth
+		: resolveAuth(
+				{
+					username: request.username,
+					password: request.password,
+					sshKey: request.sshKey,
+				},
+				env,
+				cdbResolution,
+				config,
+			);
+	// A quickchr TLS/SSH endpoint is trusted by provenance (self-signed VM cert /
+	// ephemeral host key) — `insecure` is forced with provider provenance and the
+	// provider-trust warning rides the envelope (see QuickchrConnection.insecure).
+	const insecure =
+		connection?.insecure === true
+			? {
+					value: true,
+					source: {
+						kind: "provider" as const,
+						key: `quickchr:${request.quickchr}`,
+					},
+				}
+			: resolveBooleanSetting(
+					request.insecure,
+					env,
+					"CENTRS_INSECURE",
+					false,
+					"insecure",
+					cdbResolution?.overrides.insecure,
+					config,
+				);
 
 	return {
 		command: request.command,
@@ -383,7 +445,9 @@ export async function resolveExecuteRequest(
 		maxResultsBytes,
 		yes: request.yes ?? false,
 		verbose: request.verbose ?? false,
-		warnings: cdbResolution?.warnings ?? [],
+		warnings: connection
+			? [...connection.warnings]
+			: (cdbResolution?.warnings ?? []),
 	};
 }
 
@@ -515,6 +579,7 @@ export function buildExecuteErrorEnvelopeFromResolved(
 	resolved: ResolvedExecuteRequest,
 	error: unknown,
 	validation?: EnvelopeValidationMeta,
+	trace?: ValidationTrace,
 ): ExecuteErrorEnvelope {
 	const centrsError =
 		error instanceof CentrsError
@@ -533,23 +598,133 @@ export function buildExecuteErrorEnvelopeFromResolved(
 		tips: resolvedExecuteTips(resolved),
 		meta: metaFromResolved(
 			resolved,
-			validation ?? {
-				enabled: resolved.validate.value,
-				source: resolved.validate.value
-					? ":put [:parse] + /console/inspect"
-					: "disabled",
-				result: resolved.validate.value ? "failed" : "skipped",
-				syntax: resolved.validate.value,
-				semantic: resolved.validate.value
-					? resolved.canonical.mode === "structured"
-						? false
-						: "not-applicable"
-					: false,
-			},
+			validation ??
+				trace?.validation ??
+				failedValidationMeta(resolved, error, trace),
 		),
 	};
 }
 
+/**
+ * The `meta.validation` for an error envelope built without a validation result
+ * of its own — i.e. the gate threw, or something downstream did.
+ *
+ * A stage-1 rejection is the case worth spelling out: the offline analyzer never
+ * opens a connection, so reporting the old flat
+ * `source: ":put [:parse] + /console/inspect"` / `result: "failed"` would claim
+ * a device probe that did not happen. `stages` says which one actually spoke.
+ */
+function failedValidationMeta(
+	resolved: ResolvedExecuteRequest,
+	error: unknown,
+	trace?: ValidationTrace,
+): EnvelopeValidationMeta {
+	if (!resolved.validate.value) {
+		return disabledValidationMeta();
+	}
+	const deviceSource = deviceStageSource(resolved);
+	// Script-shaped input has no `/console/inspect` half to fail, on either
+	// branch below. Reporting `semantic: false` for it would say a semantic gate
+	// ran and said no, which is a different claim from "there was none".
+	const semantic: boolean | "not-applicable" =
+		resolved.canonical.mode === "structured" ? false : "not-applicable";
+	if (isOfflineGateRejection(error)) {
+		return {
+			enabled: true,
+			source: OFFLINE_GATE_SOURCE,
+			result: "failed",
+			syntax: false,
+			semantic,
+			stages: [
+				{ stage: "offline", source: OFFLINE_GATE_SOURCE, result: "failed" },
+				{
+					stage: "device",
+					source: deviceSource,
+					result: "skipped",
+					reason: "offline analysis rejected the command; no connection opened",
+				},
+			],
+		};
+	}
+	// Only a `validation/*` error tells us the DEVICE stage rejected it — and
+	// only then do we know stage 1 passed, because stage 1 runs first and would
+	// have thrown its own (offline-tagged) error otherwise. This builder also
+	// catches everything downstream — a RouterOS fault on the run, a transport
+	// drop — which passed both stages and is served by `trace.validation`. When
+	// neither applies, `stages` is omitted rather than asserting a verdict this
+	// function cannot know.
+	const deviceRejected =
+		error instanceof CentrsError && error.code.startsWith("validation/");
+	return {
+		enabled: true,
+		source: deviceSource,
+		result: "failed",
+		syntax: true,
+		semantic,
+		...(deviceRejected
+			? {
+					stages: [
+						offlineStagePassed(trace?.offlineVerdict),
+						{
+							stage: "device" as const,
+							source: deviceSource,
+							result: "failed" as const,
+						},
+					],
+				}
+			: {}),
+	};
+}
+
+/** The device-stage validator identity for a resolved request's transport. */
+function deviceStageSource(resolved: ResolvedExecuteRequest): string {
+	return resolved.via.value === "mac-telnet" || resolved.via.value === "ssh"
+		? `:put [:parse ...] over ${resolved.via.value}`
+		: ":put [:parse] + /console/inspect";
+}
+
+/**
+ * The offline stage entry for a gate stage 1 cleared.
+ *
+ * `verdict` comes from the {@link ValidationTrace}, not from a re-run: a `warn`
+ * is an ABSTENTION, and an error envelope that flattened it to a bare `passed`
+ * would tell a consumer the analyzer judged bytes it explicitly declined to
+ * judge. An absent verdict means the caller did not thread a trace, so say
+ * nothing extra rather than invent the reason.
+ */
+function offlineStagePassed(
+	verdict: ValidationTrace["offlineVerdict"],
+): EnvelopeValidationStage {
+	return {
+		stage: "offline",
+		source: OFFLINE_GATE_SOURCE,
+		result: "passed",
+		...(verdict === "warn"
+			? { reason: "analyzer abstained on part of the input" }
+			: {}),
+	};
+}
+
+/**
+ * `validate=false`. Both stages are listed as `skipped` rather than omitted:
+ * the constitution's rule is that a gated surface always reports each stage, so
+ * a consumer reading `stages` never has to special-case the disabled shape.
+ * `reason` is left off — `enabled: false` already says why.
+ */
+function disabledValidationMeta(): EnvelopeValidationMeta {
+	return {
+		enabled: false,
+		source: "disabled",
+		result: "skipped",
+		syntax: false,
+		semantic: false,
+		stages: [
+			{ stage: "offline", source: OFFLINE_GATE_SOURCE, result: "skipped" },
+			{ stage: "device", source: "device preflight", result: "skipped" },
+		],
+	};
+}
+
 export function renderExecuteEnvelope(
 	envelope: ExecuteEnvelope,
 	format: ExecuteOutputFormat,
@@ -569,86 +744,6 @@ export function renderExecuteEnvelope(
 	}
 }
 
-/**
- * The **script-vs-structured execution gate** — centrs's load-bearing
- * discriminator (with {@link isWriteShaped}) for which validation runs and
- * whether the write-confirmation prompt fires. centrs owns this gate; the shared,
- * prose-tolerant, multi-command canonicalizer that `rosetta` / `lsp-routeros-ts`
- * publish is for *canonicalization*, never the structured-mode predicate —
- * widening what counts as `structured` is a product regression. Behavior is
- * pinned by `test/unit/execute-canonicalize-contract.test.ts`.
- *
- * centrs deliberately does **not** vendor the shared parser yet. Preconditions
- * for adopting it: (1) that contract stays green (no gate widening); (2) the
- * vendored file is clean under centrs's strict `tsconfig` (or explicitly
- * quarantined with justification); (3) `lsp-routeros-ts` also vendors/consumes
- * the same parser shape, so it is genuinely shared, not a premature first copy.
- */
-export function canonicalizeExecuteCommand(
-	input: string,
-): CanonicalExecuteCommand {
-	const asScript = (): CanonicalExecuteCommand => ({
-		mode: "script",
-		input,
-		path: "",
-		verb: "",
-		attributes: {},
-		queries: [],
-	});
-
-	const trimmed = input.trim();
-	if (!trimmed.startsWith("/")) {
-		return asScript();
-	}
-
-	const tokens = tokenizeRouterOsCli(trimmed);
-	const pathToken = tokens[0] ?? "";
-	const pathParts = pathToken.split("/").filter(Boolean);
-	if (pathParts.length < 2) {
-		return asScript();
-	}
-
-	const verb = pathParts.at(-1) ?? "";
-	const path = `/${pathParts.slice(0, -1).join("/")}`;
-	const attributes: Record<string, string> = {};
-	const queries: string[] = [];
-	for (const token of tokens.slice(1)) {
-		// `[...]` subshell selectors (e.g. `numbers=[find ...]`) cannot be
-		// represented as a structured attribute map: the inner command contains
-		// spaces this tokenizer splits on, which would mangle a write-shaped
-		// command into corrupt key=value pairs. Fall back to the raw-script path
-		// so RouterOS evaluates the subshell with its real semantics.
-		if (token.includes("[") || token.includes("]")) {
-			return asScript();
-		}
-		if (token.startsWith("?")) {
-			queries.push(token);
-			continue;
-		}
-		const separator = token.indexOf("=");
-		if (separator <= 0) {
-			return asScript();
-		}
-		attributes[token.slice(0, separator)] = token.slice(separator + 1);
-	}
-
-	return {
-		mode: "structured",
-		input,
-		path,
-		verb,
-		attributes,
-		queries,
-	};
-}
-
-export function isWriteShaped(command: CanonicalExecuteCommand): boolean {
-	return (
-		command.mode === "structured" &&
-		["add", "set", "remove"].includes(command.verb)
-	);
-}
-
 export function validateExecuteRequestShape(request: ExecuteRequest): void {
 	if (!request.command || request.command.trim().length === 0) {
 		throw new CentrsError({
@@ -660,12 +755,31 @@ export function validateExecuteRequestShape(request: ExecuteRequest): void {
 	}
 }
 
+/**
+ * The two-stage gate (GH#354): offline analysis first, then the device probe.
+ *
+ * Stage 1 runs before anything is sent, on every transport, so a syntax fault is
+ * a byte span and no round trip. It is not a substitute for stage 2 — `explain`
+ * has no per-menu schema, so it cannot see an unknown attribute — and it never
+ * reports success on the device's behalf. Stage 2 is unchanged: `:parse` (which
+ * on a console transport also covers the name-level attribute gate) plus
+ * `/console/inspect request=child` for structured input over REST/native.
+ */
 async function validateExecuteCommand(
 	resolved: ResolvedExecuteRequest,
 	backend: ProtocolAdapter,
+	trace: ValidationTrace = {},
 ): Promise<EnvelopeValidationMeta> {
+	const offline = assertOfflineSyntax(resolved.command, {
+		surface: "execute",
+		via: resolved.via.value,
+	});
+	// Recorded before stage 2 can throw, so a device rejection still reports
+	// whether stage 1 read the whole input or abstained on part of it.
+	trace.offlineVerdict = offline.verdict;
+
 	if (resolved.via.value === "mac-telnet" || resolved.via.value === "ssh") {
-		return validateConsoleParseCommand(resolved, backend);
+		return validateConsoleParseCommand(resolved, backend, offline);
 	}
 
 	await runSyntaxGate(resolved, backend);
@@ -677,10 +791,14 @@ async function validateExecuteCommand(
 			result: "passed",
 			syntax: true,
 			semantic: "not-applicable",
+			stages: passedStages(offline, ":put [:parse]"),
 		};
 	}
 
-	const availableAttributes = await inspectExecuteAttributes(resolved, backend);
+	const availableAttributes = await inspectArgumentNames(backend, [
+		...pathTokens(resolved.canonical.path),
+		resolved.canonical.verb,
+	]);
 	const requested = Object.keys(resolved.canonical.attributes);
 	const missing = requested.filter(
 		(attribute) => !availableAttributes.includes(attribute),
@@ -694,10 +812,10 @@ async function validateExecuteCommand(
 			context: {
 				path: resolved.canonical.path,
 				verb: resolved.canonical.verb,
-				attribute: missing[0],
+				parameter: missing[0],
 				requestedAttributes: requested,
 				availableAttributes,
-				validationSource: "/console/inspect request=child+completion",
+				validationSource: "/console/inspect request=child",
 			},
 		});
 	}
@@ -709,6 +827,7 @@ async function validateExecuteCommand(
 		syntax: true,
 		semantic: true,
 		availableAttributes,
+		stages: passedStages(offline, ":put [:parse] + /console/inspect"),
 	};
 }
 
@@ -716,36 +835,22 @@ async function validateExecuteCommand(
  * Validate a command over a console transport (mac-telnet or ssh) with a single
  * `:put [:parse ...]`. Unlike REST/native (a syntax gate plus a `/console/inspect`
  * semantic gate), one console `:parse` reports both `syntax error` and `bad
- * parameter <name>`, so it covers syntax and the unknown-attribute (semantic)
+ * parameter <name>`, so it covers syntax and the unknown-attribute (name-level)
  * gate at once — identical strings over mac-telnet and ssh (CHR 7.23.1 grounded;
  * see `mac-telnet-console.ts` and `ssh.ts`).
  */
 async function validateConsoleParseCommand(
 	resolved: ResolvedExecuteRequest,
 	backend: ProtocolAdapter,
+	offline: OfflineGateResult,
 ): Promise<EnvelopeValidationMeta> {
-	if (hasUnbalancedQuotes(resolved.command)) {
-		throw new CentrsError({
-			code: "validation/syntax",
-			summary:
-				"RouterOS rejected the command syntax during local quote preflight.",
-			remediation:
-				"Close the RouterOS string quote, then retry. The command was not executed.",
-			context: {
-				command: resolved.command,
-				validationSource: "local quote preflight before :put [:parse ...]",
-				via: resolved.via.value,
-			},
-			causeData: "unterminated string literal",
-		});
-	}
 	const result = await backend.execute({
 		path: "",
 		command: "",
 		script: parseScriptFor(resolved.command),
 	});
 	// Throws validation/syntax or validation/unknown-attribute on a bad parse.
-	classifyParseResult(result.ret ?? "", resolved.command);
+	classifyParseResult(result.ret ?? "", resolved.command, resolved.via.value);
 	return {
 		enabled: true,
 		source: `:put [:parse ...] over ${resolved.via.value}`,
@@ -753,31 +858,50 @@ async function validateConsoleParseCommand(
 		syntax: true,
 		semantic:
 			resolved.canonical.mode === "structured" ? true : "not-applicable",
+		stages: passedStages(
+			offline,
+			`:put [:parse ...] over ${resolved.via.value}`,
+		),
 	};
 }
 
+/**
+ * The stage breakdown for a gate both stages passed. `offline` is carried rather
+ * than re-derived so the meta reports the verdict the run actually saw — a
+ * `warn` is an abstention, and saying so is the difference between "the analyzer
+ * read all of this" and "it declined to judge part of it".
+ */
+function passedStages(
+	offline: OfflineGateResult,
+	deviceSource: string,
+): EnvelopeValidationStage[] {
+	return [
+		{
+			stage: "offline",
+			source: OFFLINE_GATE_SOURCE,
+			result: "passed",
+			...(offline.verdict === "warn"
+				? { reason: "analyzer abstained on part of the input" }
+				: {}),
+		},
+		{ stage: "device", source: deviceSource, result: "passed" },
+	];
+}
+
 async function runSyntaxGate(
 	resolved: ResolvedExecuteRequest,
 	backend: ProtocolAdapter,
 ): Promise<void> {
-	if (hasUnbalancedQuotes(resolved.command)) {
-		throw new CentrsError({
-			code: "validation/syntax",
-			summary:
-				"RouterOS rejected the command syntax during local quote preflight.",
-			remediation:
-				"Close the RouterOS string quote, then retry. The command was not executed.",
-			context: {
-				command: resolved.command,
-				validationSource: "local quote preflight before :put [:parse ...]",
-				via: resolved.via.value,
-			},
-			causeData: "unterminated string literal",
-		});
-	}
 	const script = `:put [:parse ${routerOsStringLiteral(resolved.command)}]`;
 	try {
-		await backend.execute({ path: "", command: "", script });
+		// GH#230: `:parse` never throws (CHR 7.23.3). The diagnostic rides the
+		// success value's text — over REST/native the `ret` field (HTTP 200 /
+		// `as-string`), over console the printed output. The old code only watched
+		// for a thrown transport/RouterOS error and so never rejected anything.
+		// Read the return and classify it: one `:parse` covers syntax and the
+		// unknown-attribute (name-level) gate.
+		const result = await backend.execute({ path: "", command: "", script });
+		classifyParseResult(result.ret ?? "", resolved.command, resolved.via.value);
 	} catch (error) {
 		// The preflight is a syntax gate, but `backend.execute` also surfaces
 		// connection and authentication failures (login happens lazily here).
@@ -788,6 +912,9 @@ async function runSyntaxGate(
 		if (error instanceof CentrsError && isPreflightTransportError(error)) {
 			throw error;
 		}
+		if (error instanceof CentrsError && error.code.startsWith("validation/")) {
+			throw error;
+		}
 		// If the mapped RouterOS fault carried a `(line N column M)` byte offset,
 		// keep it on the wrapped syntax error rather than dropping it.
 		const position = error instanceof CentrsError ? error.position : undefined;
@@ -818,27 +945,6 @@ function isPreflightTransportError(error: CentrsError): boolean {
 	return error.code.startsWith("transport/") || error.code.startsWith("auth/");
 }
 
-async function inspectExecuteAttributes(
-	resolved: ResolvedExecuteRequest,
-	backend: ProtocolAdapter,
-): Promise<string[]> {
-	const commandTokens = [
-		...pathTokens(resolved.canonical.path),
-		resolved.canonical.verb,
-	];
-	const children = await inspectChildren(backend, commandTokens);
-	const childAttributes = children
-		.filter(isArgumentNode)
-		.map((child) => child.name)
-		.filter(
-			(name): name is string => typeof name === "string" && name.length > 0,
-		);
-	const completionRows = await inspectCompletions(backend, commandTokens);
-	return [
-		...new Set([...childAttributes, ...extractCompletionNames(completionRows)]),
-	].sort();
-}
-
 async function runCommand(
 	resolved: ResolvedExecuteRequest,
 	backend: ProtocolAdapter,
@@ -1304,80 +1410,6 @@ function renderExecuteErrorText(
 	return lines.join("\n");
 }
 
-function hasUnbalancedQuotes(input: string): boolean {
-	let quote: '"' | "'" | undefined;
-	let escaped = false;
-	for (const char of input) {
-		if (escaped) {
-			escaped = false;
-			continue;
-		}
-		if (char === "\\") {
-			escaped = true;
-			continue;
-		}
-		if (quote) {
-			if (char === quote) {
-				quote = undefined;
-			}
-			continue;
-		}
-		if (char === '"' || char === "'") {
-			quote = char;
-		}
-	}
-	return quote !== undefined;
-}
-
-function tokenizeRouterOsCli(input: string): string[] {
-	const tokens: string[] = [];
-	let current = "";
-	let quote: '"' | "'" | undefined;
-	let escaped = false;
-	for (const char of input) {
-		if (escaped) {
-			current += char;
-			escaped = false;
-			continue;
-		}
-		if (char === "\\") {
-			escaped = true;
-			continue;
-		}
-		if (quote) {
-			if (char === quote) {
-				quote = undefined;
-			} else {
-				current += char;
-			}
-			continue;
-		}
-		if (char === '"' || char === "'") {
-			quote = char;
-			continue;
-		}
-		if (/\s/.test(char)) {
-			if (current.length > 0) {
-				tokens.push(current);
-				current = "";
-			}
-			continue;
-		}
-		current += char;
-	}
-	if (escaped) {
-		current += "\\";
-	}
-	if (current.length > 0) {
-		tokens.push(current);
-	}
-	return tokens;
-}
-
-function routerOsStringLiteral(value: string): string {
-	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-}
-
 function syntaxCause(error: unknown): unknown {
 	if (error instanceof CentrsError) {
 		return error.causeData ?? error.context ?? error.toJSON();