@tikoci/centrs 0.1.4 → 0.1.6

package/src/api-fanout.ts

@@ -39,6 +39,7 @@ import type {
 	CentrsSuccessEnvelope,
 	FanoutData,
 	FanoutSummary,
+	ValidationTrace,
 } from "./core/envelope.ts";
 import {
 	buildFanoutEnvelope,
@@ -49,6 +50,7 @@ import {
 	runFanout,
 	summarizeFanout,
 } from "./core/fanout.ts";
+import { toYaml } from "./core/yaml.ts";
 import { CentrsError, serializeCentrsError } from "./errors.ts";
 import { promptForWriteConfirmation } from "./execute.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
@@ -61,7 +63,6 @@ import {
 	type SelectionResolveInput,
 	type TargetSelection,
 } from "./resolver/index.ts";
-import { toYaml } from "./retrieve.ts";
 
 /** Compact description of the selector that produced the fan-out. */
 export interface ApiSelectionSummary {
@@ -246,6 +247,11 @@ export async function apiFanout(
 	await assertFanoutWriteConfirmed(request, requestSummary, method, expansion);
 
 	const execute = internals.execute ?? runResolvedApi;
+	// Per-target validation trace. `execute` and `onExecuteError` are separate
+	// callbacks that share only the resolved request, so the request object is
+	// the key: without it a per-target error envelope would reconstruct
+	// `meta.validation` instead of reporting the gate that actually ran (GH#354).
+	const traces = new WeakMap<ResolvedApiRequest, ValidationTrace>();
 	const sleep = internals.sleep ?? defaultFanoutSleep;
 
 	const targets = await runFanout<
@@ -292,11 +298,18 @@ export async function apiFanout(
 				target: memberTargetMeta(member),
 				warnings: member.kind === "cdb" ? [...member.resolution.warnings] : [],
 			}),
-		execute: async (resolved, member) =>
-			relabelAdhocMember(await execute(resolved), member),
+		execute: async (resolved, member) => {
+			const trace: ValidationTrace = {};
+			traces.set(resolved, trace);
+			return relabelAdhocMember(await execute(resolved, trace), member);
+		},
 		onExecuteError: (resolved, member, error) =>
 			relabelAdhocMember(
-				buildApiErrorEnvelopeFromResolved(resolved, error),
+				buildApiErrorEnvelopeFromResolved(
+					resolved,
+					error,
+					traces.get(resolved),
+				),
 				member,
 			),
 		sleep,

package/src/api.ts

@@ -21,21 +21,26 @@ import type {
 	CommonSettingsMeta,
 	SettingSource as CoreSettingSource,
 	EnvelopeValidationMeta,
+	EnvelopeValidationStage,
 	Tip,
+	ValidationTrace,
 	Warning,
 } from "./core/envelope.ts";
 import { buildTip } from "./core/envelope.ts";
 import {
-	extractCompletionNames,
-	inspectChildren,
+	inspectArgumentNames,
 	inspectChildrenOrEmpty,
-	inspectCompletions,
-	isArgumentNode,
 	isCommandNode,
 	pathTokens,
 } from "./core/inspect.ts";
+import { toYaml } from "./core/yaml.ts";
 import { CentrsError, serializeCentrsError } from "./errors.ts";
 import { promptForWriteConfirmation } from "./execute.ts";
+import {
+	assertOfflineSyntax,
+	isOfflineGateRejection,
+	OFFLINE_GATE_SOURCE,
+} from "./offline-gate.ts";
 import {
 	type ApiVerb,
 	createProtocolAdapter,
@@ -64,7 +69,6 @@ import {
 	resolveTarget,
 	toCoreSource,
 } from "./resolver/index.ts";
-import { toYaml } from "./retrieve.ts";
 
 export const apiOutputFormats = ["json", "yaml", "text"] as const;
 export type ApiOutputFormat = (typeof apiOutputFormats)[number];
@@ -97,7 +101,11 @@ export interface ApiRequest {
 	rawQuery?: readonly string[];
 	/** `--proplist` / `--attribute` property projection. */
 	proplist?: readonly string[];
-	/** `--raw`: bare RouterOS body passthrough; implies `--validate=false`. */
+	/**
+	 * `--raw`: bare RouterOS body passthrough. DEFAULTS `--validate` to false; an
+	 * explicit `validate` still wins, and its failures render through the `--raw`
+	 * error contract (#154).
+	 */
 	raw?: boolean;
 	/** `--listen`: native-api-only open-ended follow (later phase; rejected here). */
 	listen?: boolean;
@@ -124,6 +132,23 @@ export interface ApiRequest {
 	confirm?: (prompt: string) => Promise<boolean>;
 }
 
+/**
+ * The `--raw` / `--validate` precedence for a summary built BEFORE (or instead
+ * of) full resolution — a usage error, or a fan-out member that never reached
+ * `resolveApiRequest`.
+ *
+ * Ambient sources are deliberately out of reach here: this runs where the CDB
+ * and config tiers have not been loaded, so it reports the two layers it CAN
+ * see. That is why it is a shared helper rather than an inlined expression —
+ * both call sites used to spell `request.raw ? false : …`, which contradicted
+ * the resolved request by reporting `validate: false` for an explicit
+ * `--raw --validate=true` (#154).
+ */
+function summarizedValidate(request: ApiRequest): boolean {
+	if (request.validate !== undefined) return request.validate;
+	return !(request.raw ?? false);
+}
+
 export interface NormalizedApiEndpoint {
 	/** Canonical slash path with the leading `/rest` and any trailing id/`listen` removed. */
 	path: string;
@@ -247,19 +272,25 @@ export async function apiEnvelope(
 	env: Record<string, string | undefined> = Bun.env,
 ): Promise<ApiEnvelope> {
 	let resolved: ResolvedApiRequest | undefined;
+	// The gate finishes inside `runResolvedApi`, but the error envelope is built
+	// out here after the throw has unwound past it. Without the trace, a
+	// `transport/*` or `routeros/*` fault on the request — both stages already
+	// settled — reported `/console/inspect` as the validator that failed.
+	const trace: ValidationTrace = {};
 	try {
 		resolved = await resolveApiRequest(request, env);
 		await assertApiWriteConfirmed(request, resolved);
-		return await runResolvedApi(resolved);
+		return await runResolvedApi(resolved, trace);
 	} catch (error) {
 		return resolved
-			? buildApiErrorEnvelopeFromResolved(resolved, error)
+			? buildApiErrorEnvelopeFromResolved(resolved, error, trace)
 			: buildApiErrorEnvelope(request, error, env);
 	}
 }
 
 export async function runResolvedApi(
 	resolved: ResolvedApiRequest,
+	trace: ValidationTrace = {},
 ): Promise<ApiSuccessEnvelope> {
 	assertListenCapability(resolved);
 	const backend = createProtocolAdapter({
@@ -279,18 +310,15 @@ export async function runResolvedApi(
 	let tips: Tip[] = [];
 	try {
 		if (resolved.validate.value) {
-			const result = await validateApiRequest(resolved, backend);
+			const result = await validateApiRequest(resolved, backend, trace);
 			validation = result.validation;
 			tips = result.tips;
 		} else {
-			validation = {
-				enabled: false,
-				source: "disabled",
-				result: "skipped",
-				syntax: false,
-				semantic: false,
-			};
+			validation = disabledApiValidationMeta(resolved);
 		}
+		// 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(buildProtocolApiRequest(resolved));
 		return {
@@ -574,19 +602,40 @@ export async function resolveApiRequest(
 			)));
 	const via = resolveApiProtocol(request, env, listen, cdbResolution, config);
 	const format = resolveApiFormat(request, env, config);
-	// `--raw` forces validation off (constitution: --raw waiver); otherwise the
-	// inspect gate is on by default.
-	const validate: ResolvedSetting<boolean> = raw
-		? { value: false, source: { kind: "cli", key: "--raw" } }
-		: resolveBooleanSetting(
-				request.validate,
-				env,
-				"CENTRS_VALIDATE",
-				true,
-				"validate",
-				cdbResolution?.overrides.validate,
-				config,
-			);
+	// `--raw` is a PRECEDENCE LAYER, not an override (#154). It ranks below an
+	// explicit `--validate` and above every ambient source, so:
+	//
+	//   --validate=true|false   explicit CLI flag   ← wins
+	//   --raw                   → validate=false
+	//   CENTRS_VALIDATE / CDB comment-kv / config
+	//   default                 → validate=true
+	//
+	// It used to short-circuit the whole ladder, which silently discarded an
+	// explicit `--validate=true` — and env, CDB and config with it. `--raw
+	// --validate=true` is the intended way to debug `api` when centrs itself is
+	// suspect: the gate runs and a failure renders through `rawErrorPayload` as
+	// `{code,message}` on stderr with a nonzero exit, which is the `--raw` error
+	// contract for any other preflight failure. `--raw` still outranks the
+	// ambient sources rather than merely lowering the default, so it behaves the
+	// same on every machine regardless of a `CENTRS_VALIDATE` in the environment.
+	//
+	// The `--raw` arm must SHORT-CIRCUIT, not merely win a comparison: resolving
+	// the ambient layer first would parse `CENTRS_VALIDATE` even when `--raw`
+	// decides the value, so a malformed ambient value threw `settings/invalid-
+	// boolean` out of a call `--raw` had already settled — the same
+	// machine-dependence this layer exists to remove.
+	const validate: ResolvedSetting<boolean> =
+		raw && request.validate === undefined
+			? { value: false, source: { kind: "cli", key: "--raw" } }
+			: resolveBooleanSetting(
+					request.validate,
+					env,
+					"CENTRS_VALIDATE",
+					true,
+					"validate",
+					cdbResolution?.overrides.validate,
+					config,
+				);
 	const timeoutMs = resolveApiTimeout(
 		request.timeout,
 		env,
@@ -906,6 +955,9 @@ export function buildProtocolApiRequest(
 	return request;
 }
 
+/** The api device-stage validator: structured input is inspected, never `:parse`d. */
+const API_DEVICE_STAGE_SOURCE = "/console/inspect request=child";
+
 interface ApiValidationResult {
 	validation: EnvelopeValidationMeta;
 	tips: Tip[];
@@ -913,22 +965,58 @@ interface ApiValidationResult {
 
 /**
  * The structured-input gate. Because the input is a path (not a CLI string) the
- * validator is `/console/inspect`, never `:put [:parse]`. Path existence via
- * `request=child`; add/set attribute validity via `request=child`+`completion`. A
+ * validator is `/console/inspect`, never `:put [:parse]`. Path existence and
+ * add/set attribute validity both come from `request=child` — command-level
+ * `request=completion` is unsafe on RouterOS 7.12.2 (`core/inspect.ts`). A
  * `/execute` script is a CLI string → `semantic: not-applicable`.
  */
 async function validateApiRequest(
 	resolved: ResolvedApiRequest,
 	backend: ProtocolAdapter,
+	trace: ValidationTrace = {},
 ): Promise<ApiValidationResult> {
 	if (resolved.scriptMode) {
+		// `/execute` carries a CLI string, so `/console/inspect` has nothing to
+		// inspect — which until GH#354 meant the script was sent with NO gate at
+		// all (`syntax: false`, `semantic: "not-applicable"`, `result: "passed"`).
+		// The offline analyzer is the whole gate here: a syntax fault is now a
+		// byte span and no round trip, where before it reached the device.
+		const script = scriptOf(resolved);
+		const offline = script
+			? assertOfflineSyntax(script, {
+					surface: "api /execute",
+					via: resolved.via.value,
+				})
+			: undefined;
+		trace.offlineVerdict = offline?.verdict;
+		const offlineReason =
+			offline === undefined
+				? "no `script` field to analyze"
+				: offline.verdict === "warn"
+					? "analyzer abstained on part of the input"
+					: undefined;
 		return {
 			validation: {
 				enabled: true,
-				source: "/console/inspect (script, not-applicable)",
+				source: offline === undefined ? "not-applicable" : OFFLINE_GATE_SOURCE,
 				result: "passed",
-				syntax: false,
+				syntax: offline !== undefined,
 				semantic: "not-applicable",
+				stages: [
+					{
+						stage: "offline",
+						source: OFFLINE_GATE_SOURCE,
+						result: offline === undefined ? "skipped" : "passed",
+						...(offlineReason ? { reason: offlineReason } : {}),
+					},
+					{
+						stage: "device",
+						source: "/console/inspect request=child",
+						result: "skipped",
+						reason:
+							"`/execute` is a CLI string, not a menu path; RouterOS re-validates it on the run",
+					},
+				],
 			},
 			tips: [],
 		};
@@ -970,7 +1058,7 @@ async function validateApiRequest(
 		// Only reject when inspect actually surfaced the command's arguments; if it
 		// returns none, skip rather than false-reject a valid command.
 		if (isCommand && Object.keys(resolved.body).length > 0) {
-			const available = await inspectApiAttributes(backend, tokens);
+			const available = await inspectArgumentNames(backend, tokens);
 			if (available.length > 0) {
 				const requested = Object.keys(resolved.body);
 				const missing = requested.filter(
@@ -988,7 +1076,7 @@ async function validateApiRequest(
 							parameter: missing[0],
 							requestedAttributes: requested,
 							availableAttributes: available,
-							validationSource: "/console/inspect request=child+completion",
+							validationSource: "/console/inspect request=child",
 						},
 					});
 				}
@@ -1013,7 +1101,7 @@ async function validateApiRequest(
 	}
 
 	if (resolved.verb === "add" || resolved.verb === "set") {
-		const available = await inspectApiAttributes(backend, [
+		const available = await inspectArgumentNames(backend, [
 			...tokens,
 			resolved.verb,
 		]);
@@ -1033,14 +1121,14 @@ async function validateApiRequest(
 					parameter: missing[0],
 					requestedAttributes: requested,
 					availableAttributes: available,
-					validationSource: "/console/inspect request=child+completion",
+					validationSource: "/console/inspect request=child",
 				},
 			});
 		}
 		return {
 			validation: {
 				enabled: true,
-				source: "/console/inspect request=child+completion",
+				source: "/console/inspect request=child",
 				result: "passed",
 				syntax: false,
 				semantic: true,
@@ -1062,6 +1150,21 @@ async function validateApiRequest(
 	};
 }
 
+/**
+ * The `/execute` script body, when there is one to analyze.
+ *
+ * A missing or blank `script` is not this gate's error to raise:
+ * {@link buildProtocolApiRequest} already rejects it with an actionable
+ * `input/invalid-command` naming the three ways to pass one. Reporting a syntax
+ * fault for an absent field would be the wrong diagnosis.
+ */
+function scriptOf(resolved: ResolvedApiRequest): string | undefined {
+	const script = resolved.body["script"];
+	return typeof script === "string" && script.trim().length > 0
+		? script
+		: undefined;
+}
+
 function unknownPathError(resolved: ResolvedApiRequest): CentrsError {
 	return new CentrsError({
 		code: "validation/unknown-path",
@@ -1076,23 +1179,6 @@ function unknownPathError(resolved: ResolvedApiRequest): CentrsError {
 	});
 }
 
-async function inspectApiAttributes(
-	backend: ProtocolAdapter,
-	commandTokens: readonly string[],
-): Promise<string[]> {
-	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 assertApiWriteConfirmed(
 	request: ApiRequest,
 	resolved: ResolvedApiRequest,
@@ -1299,7 +1385,7 @@ export function buildApiErrorEnvelope(
 						: false,
 					listen: request.listen ?? false,
 					yes: request.yes ?? false,
-					validate: request.raw ? false : (request.validate ?? true),
+					validate: summarizedValidate(request),
 					raw: request.raw ?? false,
 					format: resolveErrorFormat(request, env),
 				},
@@ -1315,6 +1401,7 @@ export function buildApiErrorEnvelope(
 export function buildApiErrorEnvelopeFromResolved(
 	resolved: ResolvedApiRequest,
 	error: unknown,
+	trace?: ValidationTrace,
 ): ApiErrorEnvelope {
 	const centrsError = asApiError(error);
 	return {
@@ -1322,17 +1409,117 @@ export function buildApiErrorEnvelopeFromResolved(
 		error: serializeCentrsError(centrsError),
 		warnings: [...resolved.warnings],
 		tips: [],
-		meta: metaFromResolved(resolved, {
-			enabled: resolved.validate.value,
-			source: resolved.validate.value ? "/console/inspect" : "disabled",
-			result: resolved.validate.value ? "failed" : "skipped",
+		meta: metaFromResolved(
+			resolved,
+			trace?.validation ??
+				failedApiValidationMeta(resolved, centrsError, trace),
+		),
+	};
+}
+
+/**
+ * `meta.validation` for an api error envelope. A stage-1 rejection opened no
+ * connection, so the meta must not report `/console/inspect` as the validator
+ * that failed (GH#354).
+ */
+function failedApiValidationMeta(
+	resolved: ResolvedApiRequest,
+	error: CentrsError,
+	trace?: ValidationTrace,
+): EnvelopeValidationMeta {
+	if (!resolved.validate.value) {
+		return disabledApiValidationMeta(resolved);
+	}
+	if (isOfflineGateRejection(error)) {
+		return {
+			enabled: true,
+			source: OFFLINE_GATE_SOURCE,
+			result: "failed",
 			syntax: false,
-			semantic: resolved.validate.value
-				? resolved.scriptMode
-					? "not-applicable"
-					: false
-				: false,
-		}),
+			semantic: "not-applicable",
+			stages: [
+				{ stage: "offline", source: OFFLINE_GATE_SOURCE, result: "failed" },
+				{
+					stage: "device",
+					source: API_DEVICE_STAGE_SOURCE,
+					result: "skipped",
+					reason: "offline analysis rejected the script; no connection opened",
+				},
+			],
+		};
+	}
+	// `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/");
+	return {
+		enabled: true,
+		source: "/console/inspect",
+		result: "failed",
+		syntax: false,
+		semantic: resolved.scriptMode ? "not-applicable" : false,
+		...(deviceRejected
+			? { stages: [offlineApiStage(resolved, trace), deviceStageFailed()] }
+			: {}),
+	};
+}
+
+/**
+ * The offline-stage entry for an api gate that reached the device stage.
+ *
+ * Script mode is the only api shape stage 1 analyzes; a structured path request
+ * is a path plus a body, not a CLI string, so its offline stage is `skipped`
+ * with the reason spelled out rather than silently reported as passed.
+ */
+function offlineApiStage(
+	resolved: ResolvedApiRequest,
+	trace?: ValidationTrace,
+): EnvelopeValidationStage {
+	if (!resolved.scriptMode) {
+		return {
+			stage: "offline",
+			source: OFFLINE_GATE_SOURCE,
+			result: "skipped",
+			reason: "structured path request, not a CLI string (GH#354)",
+		};
+	}
+	return {
+		stage: "offline",
+		source: OFFLINE_GATE_SOURCE,
+		result: "passed",
+		...(trace?.offlineVerdict === "warn"
+			? { reason: "analyzer abstained on part of the input" }
+			: {}),
+	};
+}
+
+function deviceStageFailed(): EnvelopeValidationStage {
+	return {
+		stage: "device",
+		source: API_DEVICE_STAGE_SOURCE,
+		result: "failed",
+	};
+}
+
+/**
+ * `--validate=false` (including a bare `--raw`). Both stages are listed as
+ * `skipped` rather than omitted, so a consumer reading `stages` never has to
+ * special-case the disabled shape; `enabled: false` already carries the why.
+ */
+function disabledApiValidationMeta(
+	resolved: ResolvedApiRequest,
+): EnvelopeValidationMeta {
+	return {
+		enabled: false,
+		source: "disabled",
+		result: "skipped",
+		syntax: false,
+		semantic: resolved.scriptMode ? "not-applicable" : false,
+		stages: [
+			{ stage: "offline", source: OFFLINE_GATE_SOURCE, result: "skipped" },
+			{ stage: "device", source: API_DEVICE_STAGE_SOURCE, result: "skipped" },
+		],
 	};
 }
 
@@ -1525,7 +1712,7 @@ export function apiRequestSummaryFromRequest(
 		write: parsed ? isApiMutating(parsed, normalized.path) : false,
 		listen,
 		yes: request.yes ?? false,
-		validate: request.raw ? false : (request.validate ?? true),
+		validate: summarizedValidate(request),
 		raw: request.raw ?? false,
 		format: resolveErrorFormat(request, env),
 		query: buildApiQuery(request),

package/src/cli/api.ts

@@ -94,7 +94,7 @@ export const apiCommand: CliCommandMetadata = {
 		{
 			flag: "--raw",
 			description:
-				"Strip the envelope; emit bare RouterOS JSON. Implies `--validate=false`; does not imply `--yes`.",
+				"Strip the envelope; emit bare RouterOS JSON. Defaults `--validate` to false (an explicit `--validate=true` still runs the gate); does not imply `--yes`.",
 		},
 		{
 			flag: "--yes",

package/src/cli/btest.ts

@@ -23,10 +23,10 @@ import {
 	renderBtestClientEnvelope,
 	renderBtestServerEnvelope,
 } from "../btest.ts";
+import { toYaml } from "../core/yaml.ts";
 import { asCentrsError, formatCentrsErrorText } from "../errors.ts";
 import { describeCentrs, parseDuration } from "../index.ts";
 import type { BtestDirection, BtestProtocol } from "../protocols/btest.ts";
-import { toYaml } from "../retrieve.ts";
 import {
 	type CliCommandMetadata,
 	type CliCommandOption,

package/src/cli/explain.ts

@@ -92,7 +92,7 @@ export const explainCliCommand: CliCommandMetadata = {
 		{
 			flag: "--tokens",
 			description:
-				"Emit the total, gapless token partition behind `data.tokens[]` (provisional `class` until #264 B5: every byte not claimed by an analyzer is `unclassified`).",
+				"Emit the total, gapless token partition behind `data.tokens[]` (every byte not claimed by an analyzer is `unclassified`).",
 		},
 		{
 			flag: "--format",

package/src/cli/terminal.ts

@@ -6,6 +6,7 @@
  * `process.*`); the core relay in `../terminal.ts` stays io-agnostic.
  */
 
+import { toYaml } from "../core/yaml.ts";
 import {
 	asCentrsError,
 	CentrsError,
@@ -18,7 +19,6 @@ import {
 	type TerminalIo,
 	type TerminalRequest,
 } from "../index.ts";
-import { toYaml } from "../retrieve.ts";
 import {
 	type CliCommandMetadata,
 	expectValue,

package/src/core/envelope.ts

@@ -111,6 +111,50 @@ export interface EnvelopeTargetMeta {
 	sources?: Record<string, SettingSource>;
 }
 
+/**
+ * One stage of the two-stage validation gate (GH#354).
+ *
+ * `offline` is the corpus-gated analyzer (`src/offline-gate.ts`): it opens no
+ * connection, so a `failed` offline stage means the device was never contacted.
+ * `device` is the RouterOS-side preflight — `:put [:parse …]` and/or
+ * `/console/inspect request=child`, depending on the command and transport.
+ *
+ * Stages appear in the order they run, and a stage that did not run is still
+ * listed with `result: "skipped"`. That is the point of the array: a reader must
+ * be able to tell "the device accepted it" from "the device was never asked".
+ */
+export interface EnvelopeValidationStage {
+	stage: "offline" | "device";
+	/** Validator identity, e.g. `offline explain (canonicalizer)` or `:put [:parse]`. */
+	source: string;
+	result: "passed" | "failed" | "skipped";
+	/** Why a stage was skipped, when the reason is not simply `validate=false`. */
+	reason?: string;
+}
+
+/**
+ * Mutable sink that lets an error path report the validation that ACTUALLY ran.
+ *
+ * `runResolvedExecute` / `runResolvedApi` finish the gate and then do the real
+ * work, and the error envelope is built by a *different* function after the
+ * throw unwinds past them. Without this, a `routeros/*` fault on the run — which
+ * happens with both gate stages already green — got a reconstructed
+ * `result: "failed"` that erased the real outcome. The runner writes
+ * {@link ValidationTrace.validation} the moment the gate returns; the error
+ * builder prefers it over anything it could guess (GH#354, PR #356 review).
+ */
+export interface ValidationTrace {
+	/** The completed gate result, set once validation finishes. */
+	validation?: EnvelopeValidationMeta;
+	/**
+	 * The stage-1 verdict, recorded as soon as stage 1 returns — before stage 2
+	 * can throw. `warn` is an abstention, and an error envelope that reported it
+	 * as `passed` would be telling a consumer the analyzer read bytes it declined
+	 * to judge.
+	 */
+	offlineVerdict?: "pass" | "warn";
+}
+
 export interface EnvelopeValidationMeta {
 	enabled: boolean;
 	/** Validator identity, e.g. `/console/inspect` or `:put [:parse]`. */
@@ -121,6 +165,15 @@ export interface EnvelopeValidationMeta {
 	/** Semantic `/console/inspect` gate status, or not-applicable for script mode. */
 	semantic?: boolean | "not-applicable";
 	availableAttributes?: readonly string[];
+	/**
+	 * Per-stage detail for the gate described in
+	 * `docs/CONSTITUTION.md` → "Validation is the product".
+	 *
+	 * The flat `source` / `syntax` / `semantic` fields above stay the summary
+	 * view and keep their meaning; this is the breakdown behind them. Absent on
+	 * surfaces that have no RouterOS-command gate at all (`btest`).
+	 */
+	stages?: readonly EnvelopeValidationStage[];
 }
 
 export interface EnvelopeTimingMeta {

package/src/core/error-catalog.ts

@@ -554,7 +554,8 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 	},
 	{
 		code: "validation/syntax",
-		summary: "RouterOS rejected the command syntax during the :parse gate.",
+		summary:
+			"The command syntax was rejected by the validation gate — offline analysis, or the RouterOS :parse probe.",
 	},
 	{
 		code: "validation/unknown-attribute",