@tikoci/centrs 0.1.4 → 0.1.6

package/src/explain.ts

@@ -77,6 +77,22 @@
  *     type-axis question before it is a lexical one.
  *   - **`runtimeAcceptance` is always `"not-proven"`**, offline and live alike.
  *     It is the inspect-vs-runtime gap made machine-readable, not a placeholder.
+ *
+ * ## This module is the public offline entry — its imports are a contract
+ *
+ * `@tikoci/centrs/explain` resolves here, and the claim that offline analysis is a
+ * LIBRARY capability rests on what this file imports: nothing in the graph below
+ * it may open a connection, read CDB, or touch the filesystem, so the module
+ * bundles and runs in a browser, a Worker, or an editor host (#312).
+ *
+ * That is easy to break with one line, and it was: `toYaml` and
+ * `canonicalizeExecuteCommand` are pure, but importing them from `retrieve.ts`
+ * and `execute.ts` pulled mac-telnet (`node:dgram`), native-api (`node:crypto`)
+ * and ssh in behind them. Both now live in `src/core/`. **Before adding an
+ * import here, check it is pure** — `bun run explain:browser-consumer` walks the
+ * graph and names the offending edge, and
+ * `test/unit/explain-browser-entry.test.ts` gates it. A pure helper that lives
+ * in a transport-reaching module belongs in `src/core/`, not in an import here.
  */
 
 import type {
@@ -86,22 +102,26 @@ import type {
 	EnvelopeMeta,
 } from "./core/envelope.ts";
 import { buildTip, type Tip, type Warning } from "./core/envelope.ts";
-import { CentrsError, serializeCentrsError } from "./errors.ts";
 import {
 	type CanonicalExecuteCommand,
 	canonicalizeExecuteCommand,
 	isWriteShaped,
-} from "./execute.ts";
+} from "./core/execute-command.ts";
+import { toYaml } from "./core/yaml.ts";
+import { CentrsError, serializeCentrsError } from "./errors.ts";
 import { argSpans } from "./explain/arg-tokens.ts";
 import {
 	type ArgumentKind,
+	type Argument as ExplainArgument,
 	invalidCommandBraceOffsets,
 	lexArguments,
+	lexArgumentTokens,
 	lexValueAnchors,
 	type ValueAnchorKind,
 } from "./explain/args.ts";
 import { scopeBlocks } from "./explain/blocks.ts";
 import { braceSpans } from "./explain/brace-tokens.ts";
+import { lookupPath } from "./explain/catalog.ts";
 import {
 	analyzeCoordinates,
 	type CoordinateAnalysis,
@@ -111,16 +131,28 @@ import {
 	type DefectCode,
 	isPositionalFact,
 } from "./explain/defects.ts";
+import { escapeSpans } from "./explain/escape-tokens.ts";
 import { isKnownMenuPath } from "./explain/is-known-menu.ts";
 import { operatorSpans } from "./explain/operator-tokens.ts";
 import { type PathTokenCandidate, pathSpans } from "./explain/path-tokens.ts";
 import {
 	type Resolution,
+	rangeForResolution,
 	resolveDocument,
 	resolveStatements,
 } from "./explain/pathresolve.ts";
-import { collectStringEscapeDefects } from "./explain/quoted-string.ts";
-import { maskComments, segmentStatements } from "./explain/segment.ts";
+import { walkStringEscapes } from "./explain/quoted-string.ts";
+import {
+	documentRange,
+	type MaskedRange,
+	nestedRange,
+	rangeMask,
+	segmentStatements,
+} from "./explain/segment.ts";
+import {
+	findMissingSeparators,
+	type MissingSeparator,
+} from "./explain/separator.ts";
 import { stringSpans } from "./explain/string-tokens.ts";
 import { augmentSymbolOccurrences } from "./explain/symbol-values.ts";
 import {
@@ -138,6 +170,7 @@ import {
 	type DocumentVerbSplit,
 	resolveVerb,
 	resolveVerbsFromStatements,
+	VERBS,
 	type VerbSplit,
 } from "./explain/verbsplit.ts";
 import {
@@ -149,7 +182,6 @@ import {
 	resolveStringSetting,
 	toCoreSource,
 } from "./resolver/settings.ts";
-import { toYaml } from "./retrieve.ts";
 
 /** A half-open analyzed-byte span, the coordinate contract of `coordinates.ts`. */
 export interface ExplainSpanRange {
@@ -449,18 +481,29 @@ export type TokenFill = readonly ExplainToken[];
  * Byte-exact, inheriting the #215/#252 offset discipline. Offsets are on the
  * analyzed text; `input.positionMap` applies when normalized.
  *
- * `class` is **explicitly provisional until #264 B5** — the vocabulary here is
- * not the final LSP/SCIP legend, and every byte no analyzer claims becomes
- * `unclassified`. Filling those holes is B2, one PR per fill. `unclassified`
- * is a first-class answer, not a placeholder to be avoided.
+ * `class` is the vocabulary #264 B5 settled (see below); it is not an LSP/SCIP
+ * legend and does not try to be one. Every byte no analyzer claims becomes
+ * `unclassified`, which is a first-class answer, not a placeholder to be
+ * avoided.
  *
  * B2 so far: `dir` / `cmd` (resolved path and verb bytes, including valid path
  * slashes), `operator` (26 spellings + 2 aliases, `syntax-meta` is a residual
- * merge, never a source, #255), `arg` (argument names and their `=` as located
- * by `args.ts`), and `value` (argument value bytes and leaf array-literal
- * members from `data.values.occurrences`, quotes included, #295). Whether
- * separators or per-shape values later deserve distinct classes is #264 B5
- * vocabulary and does not move byte coverage.
+ * merge, never a source, #255), `arg` / `arg-sep` (argument names and the `=`
+ * that binds each one to its value, both located by `args.ts`), and `value`
+ * (argument value bytes and leaf array-literal members from
+ * `data.values.occurrences`, quotes included, #295).
+ *
+ * **B5 settled which merges get their own name** (`commands/explain/README.md`
+ * -> *The vocabulary, and what earns a class*, where the figures live beside
+ * the generated blocks that keep them honest): a class is split only where a
+ * consumer holding the whole envelope could not recover the distinction by
+ * joining `tokens[]` to another published surface on byte offsets. `arg-sep` is
+ * the one split that test forced, because a large minority of the `=` runs the
+ * arg fill paints belong to a statement whose strict `arguments` reading
+ * refused, so there is no `ExplainArgumentToken.valueSpan` to subtract one
+ * from. The per-spelling `operator`, per-shape `value`, and scope-versus-array
+ * `brace` merges all stay merged — the bytes, `data.values.occurrences[]`, and
+ * `structure.blocks[]` already carry those distinctions.
  */
 export type ExplainTokenClass =
 	| ExplainSpanClass
@@ -468,14 +511,37 @@ export type ExplainTokenClass =
 	| "cmd"
 	| "operator"
 	| "arg"
+	/**
+	 * The single `=` byte binding one argument name to its value (#264 B5).
+	 *
+	 * Never a comparison `=`, and the separation is fill order rather than a
+	 * byte scan: the `arg` fill offers only the `=` its own located token names,
+	 * so a comparison inside a `( )` group falls through to `operator`, and one
+	 * inside a `[ … ]` substitution stays `unclassified` where the operator fill
+	 * abstains (`src/explain/operator-tokens.ts`).
+	 */
+	| "arg-sep"
 	| "value"
 	| "string"
+	/**
+	 * One valid string-internal escape sequence — the `\` and the bytes it
+	 * escapes (#264).
+	 *
+	 * The one split B5's rule admits that naming the `=` did not make. A valid
+	 * escape is recoverable from no other published surface: only INVALID
+	 * escapes appear elsewhere, as `bad-string-escape` diagnostics. Both come
+	 * from the same walk (`walkStringEscapes`), so a token and a diagnostic
+	 * cannot disagree about which bytes are an escape, and past the first
+	 * invalid escape the walk stops claiming rather than guess.
+	 */
+	| "escaped"
 	| "brace"
 	| "unclassified";
 
 export interface ExplainToken extends ExplainSpanRange {
 	/**
-	 * Provisional until #264 B5 — do not treat as the final vocabulary.
+	 * The vocabulary #264 B5 settled — see {@link ExplainTokenClass} for what
+	 * earns a class and why the remaining merges are deliberate.
 	 * `unclassified` means no analyzer claimed this byte.
 	 */
 	class: ExplainTokenClass;
@@ -626,8 +692,8 @@ export interface ExplainData {
 	 * `--schema` / `--curl` facet pattern. Every byte belongs to exactly one
 	 * token, sorted by `start`, with no gaps and no overlaps:
 	 * `tokens.map(t => input.slice(t.start, t.end)).join("") === input`.
-	 * The `class` field is provisional until #264 B5; every byte no analyzer
-	 * claims is `unclassified`.
+	 * `class` is the vocabulary #264 B5 settled ({@link ExplainTokenClass});
+	 * every byte no analyzer claims is `unclassified`.
 	 */
 	tokens?: ExplainToken[];
 	diagnostics: ExplainDiagnostic[];
@@ -678,6 +744,8 @@ const EV = {
 	paths: "e12",
 	strings: "e13",
 	braces: "e14",
+	separators: "e15",
+	escapes: "e16",
 } as const;
 
 type EvidenceKey = keyof typeof EV;
@@ -792,6 +860,26 @@ const EVIDENCE: Record<EvidenceKey, ExplainEvidence> = {
 		basis: "heuristic",
 		outcome: "ok",
 	},
+	/**
+	 * `heuristic`, and #252 is the reason rather than caution: the accepted
+	 * escape set is a ratified offline rule that a live probe CAN overturn, and
+	 * once did. The manual's "Constant Escape Sequences" table turned out to be
+	 * a lower bound — the CHR byte sweep found `\?` missing from it — so the
+	 * set pinned in `src/explain/quoted-string.ts` is the best current reading
+	 * of a device's answer, not a deterministic reading of the input bytes.
+	 * A future RouterOS could accept one more.
+	 *
+	 * Cited by the `escaped` tokens AND by `bad-string-escape`: one walk, one
+	 * evidence entry. That defect used to cite `resolveSymbols`, which never
+	 * produced it — `symbols.ts` raises the different `bad-escape` code.
+	 */
+	escapes: {
+		id: EV.escapes,
+		source: "canonicalizer",
+		probe: "walkStringEscapes",
+		basis: "heuristic",
+		outcome: "ok",
+	},
 	braces: {
 		id: EV.braces,
 		source: "canonicalizer",
@@ -799,6 +887,19 @@ const EVIDENCE: Record<EvidenceKey, ExplainEvidence> = {
 		basis: "heuristic",
 		outcome: "ok",
 	},
+	/**
+	 * `heuristic`: the run is decided from the frozen verb vocabulary and the
+	 * shipped structure table, both of which a live probe could overturn on a
+	 * menu the table does not list. The rejection it reports is device-grounded
+	 * (`src/explain/separator.ts`); which byte runs are that shape is not.
+	 */
+	separators: {
+		id: EV.separators,
+		source: "canonicalizer",
+		probe: "findMissingSeparators",
+		basis: "heuristic",
+		outcome: "ok",
+	},
 };
 
 /** Diagnostic rendering for each defect class. */
@@ -837,6 +938,14 @@ const DEFECT_DIAGNOSTICS: Record<
 		message: () =>
 			"unquoted `#` is a syntax error here — quote it where a value is accepted, or move it to statement-leading position to start a comment",
 	},
+	// #355. Not a quote-balance rule: `name='abc'` and `:put 'abc'` are rejected
+	// too. `'` simply is not a RouterOS token, so the remedy is the double quote,
+	// never a matching apostrophe.
+	"invalid-apostrophe": {
+		severity: "error",
+		message: () =>
+			'`\'` is not a RouterOS token — only `"` opens a string; use `"` here, or put the apostrophe inside a `"`-string',
+	},
 	// centrs's own resource bound, not a RouterOS rule. The input may be entirely
 	// legal; what is reported is that the analyzer stopped descending, so the
 	// honest severity is a warning about incomplete analysis.
@@ -857,6 +966,38 @@ const DEFECT_DIAGNOSTICS: Record<
 	},
 };
 
+/**
+ * Keep only the EARLIEST `invalid-apostrophe`, document-wide (#355).
+ *
+ * The rule suppresses repeats within one scan, but a nested scope body is a
+ * SEPARATE scan — `segmentScopeBody` is called per block and its defects are
+ * rebased in — so `:put 'a'; :if (true) do={ :put 'b' }` produced one from each.
+ * The device reports one error and stops, so a second occurrence is not an
+ * independent finding no matter which scope it sits in, and the contract is
+ * stated document-wide.
+ *
+ * Collapsing HERE rather than threading a flag through the walkers is the point:
+ * `segmentStatements` and `segmentScopeBody` stay pure per call, which is what
+ * lets a body be segmented on its own. The other classes are deliberately
+ * untouched — two `unclosed` delimiters ARE two findings.
+ */
+function collapseToFirstApostrophe(
+	defects: readonly AttributedDefect[],
+): AttributedDefect[] {
+	let seen = false;
+	const out: AttributedDefect[] = [];
+	for (const entry of [...defects].sort(
+		(a, b) => a.defect.start - b.defect.start,
+	)) {
+		if (entry.defect.code === "invalid-apostrophe") {
+			if (seen) continue;
+			seen = true;
+		}
+		out.push(entry);
+	}
+	return out;
+}
+
 /** A defect plus the analysis pass that raised it. */
 interface AttributedDefect {
 	defect: Defect;
@@ -910,6 +1051,17 @@ function attributeDefects(
 
 /** Build `input.positionMap`: coalesced identity runs, one entry per non-ASCII code point. */
 function positionMap(a: CoordinateAnalysis): ExplainPositionMapEntry[] {
+	// An all-ASCII input coalesces to the single identity run the loop below
+	// would build, so say it rather than walk one object per character (#322).
+	if (a.ascii)
+		return a.original.length === 0
+			? []
+			: [
+					{
+						analyzed: { start: 0, end: a.original.length },
+						originalUtf16: { start: 0, end: a.original.length },
+					},
+				];
 	const out: ExplainPositionMapEntry[] = [];
 	let run: ExplainPositionMapEntry | null = null;
 	for (const r of a.runs) {
@@ -972,8 +1124,8 @@ export function residualRanges(
  *
  * Every byte of `[0, bytes)` belongs to exactly one token: `spans` are
  * placed sorted, no gaps become `unclassified`, and the result is sorted by
- * `start` with no overlaps and `join(slice) === input`. The `class` field is
- * provisional until #264 B5.
+ * `start` with no overlaps and `join(slice) === input`. See
+ * {@link ExplainTokenClass} for what `class` may be and why.
  *
  * B2: `buildTokens` now takes an **ordered list of fills**. Fill 0 claims
  * first, fill 1 sees only the residual of fill 0, and so on — the argument
@@ -1092,8 +1244,8 @@ export interface ExplainCommandOptions {
 	 * Emit the total, gapless token partition behind `data.tokens[]`.
 	 *
 	 * Mirrors `--complete` / `--schema` / `--curl`: an opt-in facet whose
-	 * presence changes the result. The `class` field is provisional until
-	 * #264 B5.
+	 * presence changes the result. See {@link ExplainTokenClass} for the
+	 * vocabulary `class` draws on (#264 B5).
 	 */
 	tokens?: boolean;
 }
@@ -1113,14 +1265,47 @@ export function explainCommand(
 	// one byte standing in for every non-ASCII one, so an index into it IS a
 	// document byte offset. Decoding it once here keeps `statementOf` and the
 	// string-escape walk from re-deriving the same string.
-	const analyzed = new TextDecoder().decode(coordinates.analyzed);
+	const analyzed = coordinates.ascii
+		? input
+		: new TextDecoder().decode(coordinates.analyzed);
+	// The whole document as a masked range, in `analyzed` coordinates, derived
+	// ONCE.
+	//
+	// Four passes below read the same statement — the strict argument reading,
+	// the tolerant token stream, the brace diagnostic and the value anchors —
+	// and each masked that statement's text for itself. A statement's text
+	// carries its whole nested `do={…}` subtree, so on a 60 KiB document nested
+	// 64 deep those four passes masked 15.8 MB between them. A statement's mask
+	// is this mask restricted to its span (see `segment.ts` → `MaskedRange`), and
+	// `analyzed` is ASCII by construction, so the offsets need no coordinate test.
+	const analyzedRange = documentRange(analyzed, coordinates.ascii);
 	const segmented = segmentStatements(input);
 	const statementAnalysis = resolveStatements(input);
-	const verbs = resolveVerbsFromStatements(statementAnalysis);
+	const sourceRange = coordinates.ascii ? analyzedRange : undefined;
+	const verbs = resolveVerbsFromStatements(statementAnalysis, sourceRange);
 	const brackets = resolveDocument(input);
-	const write = containsWriteFromAnalyses(statementAnalysis, brackets);
+	const write = containsWriteFromAnalyses(
+		statementAnalysis,
+		brackets,
+		sourceRange,
+	);
 	const symbols = resolveSymbols(input);
 
+	// ONE escape walk, read twice (#264): its invalid half is a
+	// `bad-string-escape` diagnostic and its valid half is the `escaped` token
+	// fill further down. Walking separately for each would let the diagnostics
+	// and the token stream disagree about which bytes are an escape.
+	//
+	// The third argument only decides whether the valid spans are RETAINED, not
+	// whether they are validated, so gating it on the token facet cannot change
+	// a diagnostic — it just stops a caller who never asked for `data.tokens`
+	// from paying for a span object per escape.
+	const stringEscapes = walkStringEscapes(
+		analyzed,
+		segmented.comments,
+		options.tokens === true,
+	);
+
 	// Every analyzer re-derives the document's defects from its own walk, so a
 	// defect two analyzers both see must be reported once — and tagged with the
 	// analyzer that RAISED it, not with whichever list was merged first. The
@@ -1130,14 +1315,22 @@ export function explainCommand(
 	// the segmenter's delimiter stack is a `direct` reading). Attributing all of
 	// them to the segmenter said "direct/segmentStatements" about a fact the
 	// segmenter cannot produce.
-	const defects = attributeDefects([
-		[EV.segment, segmented.defects],
-		[EV.statements, verbs.defects],
-		[EV.subcommands, brackets.defects],
-		[EV.write, write.defects],
-		[EV.symbols, symbols.defects],
-		[EV.symbols, collectStringEscapeDefects(analyzed, segmented.comments)],
-	]);
+	//
+	// `bad-string-escape` is the same mistake one module over, and #264 is what
+	// made it fixable: it cited `resolveSymbols`, which never produced it —
+	// `symbols.ts` raises the DIFFERENT `bad-escape` code. Until the escape walk
+	// had an evidence entry of its own there was nothing truer to cite; now
+	// there is, and the token and the diagnostic cite the same one.
+	const defects = collapseToFirstApostrophe(
+		attributeDefects([
+			[EV.segment, segmented.defects],
+			[EV.statements, verbs.defects],
+			[EV.subcommands, brackets.defects],
+			[EV.write, write.defects],
+			[EV.symbols, symbols.defects],
+			[EV.escapes, stringEscapes.defects],
+		]),
+	);
 
 	// From the SPLITS, not from the segmentation. The resolver flattens `do={…}`
 	// bodies in after their parent, so its list is longer than the top-level
@@ -1145,17 +1338,40 @@ export function explainCommand(
 	// the first block. Each split carries its own document-space span.
 	//
 	const readStatements: ExplainStatement[] = verbs.splits.map((split) =>
-		statementOf(split, analyzed),
+		statementOf(split, analyzed, analyzedRange),
 	);
 	const canonical = canonicalizeExecuteCommand(input);
-	const statements = enforceGateParity(readStatements, canonical).map(
-		(statement, index) =>
-			withStatementTransport(
-				statement,
-				verbs.splits[index]?.text ?? "",
-				options,
-			),
+	// The skip-tolerant token stream every TOKEN-LEVEL rule reads (#316), one
+	// list per split. It is not `statement.arguments`: that reading stays
+	// all-or-nothing because its consumer renders a runnable request, and a token
+	// carrying `undecided` has no value to render. These two never disagree about
+	// where a token starts or ends — `args.ts` owns the one boundary walk.
+	const argumentTokens = readStatements.map((statement, index) => {
+		const split = verbs.splits[index];
+		return split === undefined || statement.kind !== "command"
+			? []
+			: argumentTokensOf(split, analyzed, analyzedRange);
+	});
+	// #311: the second command-shaped run is found on the statement's OWN
+	// argument tokens, then the reading is degraded — in that order, because the
+	// tokens are the evidence for the diagnostic and the refusal both. Transport
+	// runs after, so it classifies the degraded reading rather than a list the
+	// device never accepted.
+	const separators = readStatements.map((statement, index) =>
+		statement.resolution === "resolved"
+			? findMissingSeparators(argumentTokens[index] ?? [])
+			: [],
 	);
+	const gated = enforceGateParity(readStatements, canonical);
+	const statements = gated.map((statement, index) => {
+		const runs = separators[index] ?? [];
+		return withStatementTransport(
+			withoutSeparatedArguments(statement, runs),
+			verbs.splits[index]?.text ?? "",
+			options,
+			runs.length === 0 ? undefined : rejectedBySeparator(runs),
+		);
+	});
 
 	const diagnostics: ExplainDiagnostic[] = [
 		...defects.map(({ defect: d, ev }) => {
@@ -1168,7 +1384,8 @@ export function explainCommand(
 				ev,
 			};
 		}),
-		...invalidCommandBraceDiagnostics(verbs.splits, analyzed),
+		...invalidCommandBraceDiagnostics(verbs.splits, analyzed, analyzedRange),
+		...separators.flatMap((runs) => runs.map(missingSeparatorDiagnostic)),
 		...statements.flatMap((s) => diagnosticsForStatement(s)),
 	].sort(
 		(a, b) =>
@@ -1176,7 +1393,12 @@ export function explainCommand(
 			severityRank(b.severity) - severityRank(a.severity),
 	);
 
-	const valueFacts = valuesOf(verbs.splits, analyzed);
+	const valueFacts = valuesOf(
+		verbs.splits,
+		analyzed,
+		analyzedRange,
+		separators,
+	);
 	const spans: ExplainSpan[] = [
 		...segmented.comments.map((c) => ({
 			start: c.start,
@@ -1219,8 +1441,8 @@ export function explainCommand(
 
 	// B2/B3 fill order — the argument order IS the order (#290 design decision 1).
 	// `spans` (proof-only: comment + variables) claims first; path, argument,
-	// value, then string/brace, then operator fills each see only the residual
-	// left before them. Structural ambiguity (`/` path vs division, `=` arg sep
+	// escape, value, then string/brace, then operator fills each see only the
+	// residual left before them. Structural ambiguity (`/` path vs division, `=` arg sep
 	// vs comparison) therefore resolves by the analyzer that already proved
 	// ownership, not by a wider byte scanner. The operator scanner keeps its
 	// conservative guards for bytes no earlier fill can decide.
@@ -1243,11 +1465,17 @@ export function explainCommand(
 				return [
 					{
 						text: resolution.inner,
-						span: {
-							start: resolution.span.start + 1,
-							end: resolution.span.end - 1,
-						},
-						split: resolveVerb(resolution.inner, resolution.context),
+						// `innerSpan`, never `span ± 1`: `span` covers `[…]` for a bare
+						// substitution but `$[…]` for an interpolated one, so the
+						// arithmetic was one byte early inside a string and `pathSpans`
+						// dropped every such candidate on its text check — leaving a
+						// resolved command to the string fill (#325).
+						span: resolution.innerSpan,
+						split: resolveVerb(
+							resolution.inner,
+							resolution.context,
+							rangeForResolution(resolution) ?? documentRange(resolution.inner),
+						),
 						ev: EV.paths,
 					},
 				];
@@ -1258,8 +1486,19 @@ export function explainCommand(
 			...spans,
 			...pathSpansList,
 		]);
-		const argCandidates = statements.flatMap((s) =>
-			s.arguments?.read === true ? s.arguments.tokens : [],
+		// Every WITHDRAWN reading contributes nothing, exactly as before #316: a
+		// second command-shaped run (`withoutSeparatedArguments`) and a gate-parity
+		// disagreement (`enforceGateParity`) both mean centrs cannot say which
+		// bytes are this command's arguments, and painting `name=` runs inside one
+		// would be that claim in lexical clothing. Everything else now paints from
+		// the tolerant stream, so `gateway=$g` gets its name and `=` claimed where
+		// the strict reading left the whole statement `unclassified`.
+		const argCandidates = gated.flatMap((statement, index) =>
+			(separators[index]?.length ?? 0) > 0 ||
+			(readStatements[index]?.arguments?.read === true &&
+				statement.arguments?.read !== true)
+				? []
+				: (argumentTokens[index] ?? []),
 		);
 		const argSpansList = argSpans(analyzed, residual1, argCandidates);
 		const residual2 = residualRanges(analyzed.length, [
@@ -1267,39 +1506,58 @@ export function explainCommand(
 			...pathSpansList,
 			...argSpansList,
 		]);
-		const valueSpansList = valueSpans(
+		// An escape is interior to a quoted run, so it claims BEFORE the two
+		// fills that would otherwise swallow it whole (#264) — it takes the
+		// residual `value` used to see, and `value` and `string` then fragment
+		// around what it claimed.
+		const escapeSpansList = escapeSpans(
 			analyzed,
 			residual2,
-			valueFacts.occurrences,
+			stringEscapes.escapes,
 		);
 		const residual3 = residualRanges(analyzed.length, [
 			...spans,
 			...pathSpansList,
 			...argSpansList,
-			...valueSpansList,
+			...escapeSpansList,
 		]);
-		const stringSpansList = stringSpans(analyzed, residual3);
+		const valueSpansList = valueSpans(
+			analyzed,
+			residual3,
+			valueFacts.occurrences,
+		);
 		const residual4 = residualRanges(analyzed.length, [
 			...spans,
 			...pathSpansList,
 			...argSpansList,
+			...escapeSpansList,
 			...valueSpansList,
-			...stringSpansList,
 		]);
-		const braceSpansList = braceSpans(analyzed, residual4);
+		const stringSpansList = stringSpans(analyzed, residual4);
 		const residual5 = residualRanges(analyzed.length, [
 			...spans,
 			...pathSpansList,
 			...argSpansList,
+			...escapeSpansList,
+			...valueSpansList,
+			...stringSpansList,
+		]);
+		const braceSpansList = braceSpans(analyzed, residual5);
+		const residual6 = residualRanges(analyzed.length, [
+			...spans,
+			...pathSpansList,
+			...argSpansList,
+			...escapeSpansList,
 			...valueSpansList,
 			...stringSpansList,
 			...braceSpansList,
 		]);
-		const opSpans = operatorSpans(analyzed, residual5);
+		const opSpans = operatorSpans(analyzed, residual6);
 		const fills: TokenFill[] = [
 			spans,
 			pathSpansList,
 			argSpansList,
+			escapeSpansList,
 			valueSpansList,
 			stringSpansList,
 			braceSpansList,
@@ -1311,7 +1569,7 @@ export function explainCommand(
 	return {
 		input: {
 			bytes: coordinates.analyzed.length,
-			normalized: coordinates.runs.some((r) => !r.ascii),
+			normalized: !coordinates.ascii,
 			truncated: false,
 			positionMap: positionMap(coordinates),
 		},
@@ -1347,6 +1605,7 @@ function withStatementTransport(
 	statement: ExplainStatement,
 	source: string,
 	options: ExplainCommandOptions,
+	rejected?: string,
 ): ExplainStatement {
 	if (statement.kind !== "command" || statement.arguments === undefined)
 		return statement;
@@ -1357,6 +1616,7 @@ function withStatementTransport(
 				command: statement.command,
 				arguments: statement.arguments,
 				source,
+				...(rejected === undefined ? {} : { rejected }),
 			},
 			{ renderCurl: options.curl, evidenceId: EV.transport },
 		),
@@ -1381,12 +1641,13 @@ function withStatementTransport(
 function statementOf(
 	split: DocumentVerbSplit,
 	analyzed: string,
+	analyzedRange: MaskedRange,
 ): ExplainStatement {
 	const reading = readingOf(split);
 	return {
 		span: { start: split.span.start, end: split.span.end },
 		...(reading.kind === "command"
-			? withArguments(reading, split, analyzed)
+			? withArguments(reading, split, analyzed, analyzedRange)
 			: reading),
 		contextCertain: split.contextCertain,
 		ev: EV.statements,
@@ -1410,8 +1671,9 @@ function withArguments(
 	reading: ExplainCommandReading,
 	split: DocumentVerbSplit,
 	analyzed: string,
+	analyzedRange: MaskedRange,
 ): ExplainCommandReading {
-	const read = argumentsOf(split, analyzed);
+	const read = argumentsOf(split, analyzed, analyzedRange);
 	return {
 		...reading,
 		command:
@@ -1436,6 +1698,7 @@ function withArguments(
 function argumentsOf(
 	split: DocumentVerbSplit,
 	analyzed: string,
+	analyzedRange: MaskedRange,
 ): { arguments: ExplainArguments; args?: Record<string, string> } {
 	if (split.argsAt === null)
 		return {
@@ -1453,7 +1716,11 @@ function argumentsOf(
 				why: "this statement's bytes are not addressable: its text was normalized (non-ASCII), or its span was widened to the enclosing statement",
 			},
 		};
-	const lexed = lexArguments(text, split.argsAt);
+	const lexed = lexArguments(
+		text,
+		split.argsAt,
+		nestedRange(analyzedRange, start, end),
+	);
 	if (!lexed.read) return { arguments: lexed };
 	return {
 		args: lexed.args,
@@ -1477,9 +1744,113 @@ function argumentsOf(
 	};
 }
 
+/**
+ * The statement's skip-tolerant argument token stream, rebased into document
+ * space (#316).
+ *
+ * Same two guards as {@link argumentsOf}, for the same reason: `argsAt` indexes
+ * the statement's own text, so offsets are only rebased when the analyzed
+ * slice really is that text. What differs is only the reading — the tokens come
+ * back with the undecodable ones located rather than the whole list discarded.
+ * A statement that is not addressable, or has no verb, yields no tokens at all, which is the
+ * same silence the strict reading gives it.
+ */
+function argumentTokensOf(
+	split: DocumentVerbSplit,
+	analyzed: string,
+	analyzedRange: MaskedRange,
+): ExplainArgument[] {
+	if (split.argsAt === null) return [];
+	const { start, end } = split.span;
+	const text = analyzed.slice(start, end);
+	if (text !== split.text) return [];
+	return lexArgumentTokens(
+		text,
+		split.argsAt,
+		nestedRange(analyzedRange, start, end),
+	).tokens.map((token) => ({
+		...token,
+		span: { start: start + token.span.start, end: start + token.span.end },
+		...(token.valueSpan === undefined
+			? {}
+			: {
+					valueSpan: {
+						start: start + token.valueSpan.start,
+						end: start + token.valueSpan.end,
+					},
+				}),
+	}));
+}
+
+/**
+ * A second command-shaped run, said out loud (#311).
+ *
+ * `error`, not `warning`: the abstention vocabulary is for input with several
+ * valid schema-free readings, and this one has none — RouterOS answers every
+ * probed spelling of this shape with `bad parameter <token>` or
+ * `expected end of command` (`src/explain/separator.ts`). What the message may
+ * claim is bounded by the same head-dependence: it says the bytes READ as a
+ * second command, which is centrs's own heuristic reading, and that RouterOS
+ * rejects the statement, which is the grounded part. It does not say which byte
+ * the device will name, because that is per-menu schema — on a head whose value
+ * slot takes a bare positional the path is absorbed into it and the VERB is
+ * refused instead (`:put /ip/route print` → `/putmessage=/ip/route` plus
+ * `bad parameter print`, CHR 7.24.2). The span is the whole second run so an
+ * editor can highlight what has to move; `insertAt` is where the separator
+ * goes, which is that span's start.
+ */
+function missingSeparatorDiagnostic(run: MissingSeparator): ExplainDiagnostic {
+	return {
+		code: "explain/canonicalizer/missing-statement-separator",
+		severity: "error",
+		message: `missing statement separator: \`${run.path}\` is a menu path and \`${run.verb}\` a command verb, so this reads as a second command with no separator before it, and RouterOS rejects the statement (\`bad parameter\` or \`expected end of command\`, on a token that depends on the head's own argument names) — insert \`;\` or a newline before \`${run.path}\``,
+		span: { start: run.span.start, end: run.span.end },
+		ev: EV.separators,
+	};
+}
+
+/**
+ * Withdraw an argument reading the second run contradicts (#311).
+ *
+ * Same move `enforceGateParity` makes, for the same reason: the argument list is
+ * all-or-nothing because a partially-read one changes what the rendered command
+ * means. Reporting `gateway=` as an attribute of `/ip/address add` is the false
+ * confident reading #311 names, and the device says the withdrawal is right
+ * rather than merely cautious — `/ip/address add interface=ether1 /ip/route add
+ * placeholder` lowers to `address=placeholder;;interface=ether1` on CHR 7.24.2, a phantom
+ * attribute the source never wrote, because the second run's words can
+ * abbreviate the HEAD's argument names. Which head arguments exist is schema,
+ * so offline cannot predict when that happens and must not publish either
+ * reading.
+ *
+ * The statement itself stays `resolved`: `/ip/address add` really is the head,
+ * the device highlight agrees, and the source is one invalid statement rather
+ * than two fabricated valid ones.
+ */
+function withoutSeparatedArguments(
+	statement: ExplainStatement,
+	runs: readonly MissingSeparator[],
+): ExplainStatement {
+	if (runs.length === 0 || statement.kind !== "command") return statement;
+	if (statement.arguments?.read !== true) return statement;
+	const { args: _dropped, ...command } = statement.command;
+	return {
+		...statement,
+		command,
+		arguments: { read: false, why: rejectedBySeparator(runs) },
+	};
+}
+
+/** The one sentence both the withdrawn argument list and transport refuse on. */
+function rejectedBySeparator(runs: readonly MissingSeparator[]): string {
+	const first = runs[0];
+	return `a second command-shaped run (\`${first?.path} ${first?.verb}\`) sits in this operand stream with no \`;\` or newline before it, so this is not one accepted statement`;
+}
+
 function invalidCommandBraceDiagnostics(
 	splits: readonly DocumentVerbSplit[],
 	analyzed: string,
+	analyzedRange: MaskedRange,
 ): ExplainDiagnostic[] {
 	const out: ExplainDiagnostic[] = [];
 	for (const split of splits) {
@@ -1504,18 +1875,46 @@ function invalidCommandBraceDiagnostics(
 			)
 		) {
 			const braceAt = split.argsAt + leadingBraceAt;
-			const structural = maskComments(text);
+			const structural = rangeMask(nestedRange(analyzedRange, start, end));
 			const trimmed = structural.slice(braceAt + 1).trimStart();
 			if (trimmed.length === 0 || trimmed[0] === "}") {
 				menuBraceAt = braceAt;
+			} else if (trimmed[0] === ":" || trimmed[0] === "/") {
+				// A menu block body is a statement list, and a statement may be a
+				// scripting directive or an ABSOLUTE command — neither of which the
+				// enclosing menu can vouch for, and neither of which any array literal
+				// can start with. `/interface { ethernet { :put x } }` is corpus 521,
+				// accepted on 7.21.5/7.23.5/7.24.2/7.25beta3 as
+				// `(evl /interface/ethernet/ (evl /putmessage=…))` — #348.
+				menuBraceAt = braceAt;
 			} else {
-				const match = /^\/?([A-Za-z][A-Za-z0-9._-]*)/.exec(trimmed);
+				const match = /^([A-Za-z][A-Za-z0-9._-]*)/.exec(trimmed);
 				if (match) {
 					const firstWord = match[1] as string;
+					// A menu block's body may open with a SUBMENU (`/ip { firewall …`)
+					// or with a COMMAND of the menu itself (`/ip { address { print } }`,
+					// whose inner brace is a body over `/ip/address`) — #348. Requiring
+					// a submenu rejected the second shape, and the device accepts it:
+					// `:parse` lowers it to `(evl (evl (evl /ip/address/print)))` on
+					// 7.21.5 and 7.24.2, and `/interface { ethernet { print } }` the same
+					// way, while `/ip { zzznotamenu { print } }` is rejected there.
+					//
+					// The command half asks the FROZEN verb vocabulary and the catalog,
+					// never a per-menu schema: `VERBS` is the thirteen CRUD verbs that
+					// exist at essentially every configuration menu (`verbs.ts`), and
+					// `lookupPath` names the menu-specific commands. The catalog carries
+					// no `/ip/address/print` row and never will — that is decision 3, not
+					// a gap to fill. An array literal opens with a digit or a quote and
+					// never reaches this identifier branch at all, so `{1;2}` is still
+					// diagnosed.
 					const isMenuContainer = split.candidates.some((candidate) => {
 						const segments = candidate.split("/").filter(Boolean);
 						if (!isKnownMenuPath(segments)) return false;
-						return isKnownMenuPath([...segments, firstWord]);
+						return (
+							isKnownMenuPath([...segments, firstWord]) ||
+							VERBS.has(firstWord) ||
+							lookupPath([...segments, firstWord])?.kind === "command"
+						);
 					});
 					if (isMenuContainer) menuBraceAt = braceAt;
 				}
@@ -1525,6 +1924,7 @@ function invalidCommandBraceDiagnostics(
 			text,
 			split.argsAt,
 			split.path === "/" ? split.verb : undefined,
+			nestedRange(analyzedRange, start, end),
 		)) {
 			if (at === menuBraceAt) continue;
 			out.push({
@@ -1540,18 +1940,40 @@ function invalidCommandBraceDiagnostics(
 	return out;
 }
 
-/** Compose safely located literals into the three-axis #225 value surface. */
+/**
+ * Compose safely located literals into the three-axis #225 value surface.
+ *
+ * `separators` is indexed by split, and its first run is a CUT (#311): from that
+ * byte on, the operand stream belongs to a second command the device never let
+ * start, so no value there can be attributed. On the two probed rows the device
+ * itself draws the line in the same place — `/ip/address add interface=ether1
+ * /ip/route add gateway=…` is read with `gateway` as the VALUE of `address=`
+ * (never as an attribute name), while the head's own `interface=ether1` survives
+ * into the IL, and `/system/note set note=hello /ip/route add …` likewise keeps
+ * `note=hello`. So the cut withdraws what the run contradicts and keeps what it
+ * does not.
+ *
+ * Not "every value in a degraded statement": `values` is deliberately an axis of
+ * its own rather than a projection of `arguments`, and the value census pins a
+ * large retained population in statements whose strict REST reading abstains
+ * (`commands/explain/README.md`, generated block). Widening this to the whole
+ * statement would contradict that measured contract.
+ */
 function valuesOf(
 	splits: readonly DocumentVerbSplit[],
 	analyzed: string,
+	analyzedRange: MaskedRange,
+	separators: readonly (readonly MissingSeparator[])[],
 ): ExplainValues {
 	const occurrences: ExplainValueOccurrence[] = [];
-	for (const split of splits) {
+	for (const [splitIndex, split] of splits.entries()) {
 		if (split.resolution !== "resolved" || split.argsAt === null) continue;
+		const cut = separators[splitIndex]?.[0]?.insertAt;
 		const { start, end } = split.span;
 		const text = analyzed.slice(start, end);
 		if (text !== split.text) continue;
 		const anchored = lexValueAnchors(text, split.argsAt, {
+			range: nestedRange(analyzedRange, start, end),
 			// A `{…}` array literal is legal only in a ROOT scripting directive's
 			// value slot; `/ip/dns/set servers={…}` and `:log info message={…}` are
 			// both device syntax errors at the `{`. `path` is how that position is
@@ -1563,6 +1985,11 @@ function valuesOf(
 		// advisory and never turn the later refusal reason into a diagnostic.
 		const ids = new Map<number, string>();
 		for (const [index, anchor] of anchored.anchors.entries()) {
+			// A token that reaches into the second run is not this statement's to
+			// name. Token spans never straddle the cut — the run's path is its own
+			// positional token, so a `{…}` or quoted value either ends before it or
+			// starts after it — which is why a dropped array cannot orphan a member.
+			if (cut !== undefined && start + anchor.tokenSpan.end > cut) continue;
 			const hints: ValueShape[] =
 				// A source-proved shape wins outright: the delimiters prove `array`,
 				// and an `=` that binds no key proves `str` or `bool` (#258). None is
@@ -1668,7 +2095,13 @@ function subcommandOf(r: Resolution): ExplainSubcommand {
 					resolution: "unknown" as const,
 					unresolved: r.unresolved ?? "no reading of this substitution",
 				}
-			: readingOf(resolveVerb(r.inner, r.context));
+			: readingOf(
+					resolveVerb(
+						r.inner,
+						r.context,
+						rangeForResolution(r) ?? documentRange(r.inner),
+					),
+				);
 	return {
 		span: { start: r.span.start, end: r.span.end },
 		context: r.context,
@@ -1867,8 +2300,8 @@ export interface ExplainEnvelopeOptions {
 	/**
 	 * Include the gapless token partition behind `data.tokens[]`.
 	 *
-	 * Mirrors `--complete` / `--schema` / `--curl` facet pattern. Provisional
-	 * vocabulary until #264 B5.
+	 * Mirrors `--complete` / `--schema` / `--curl` facet pattern. The vocabulary
+	 * is `ExplainTokenClass` (#264 B5).
 	 */
 	tokens?: boolean;
 	tips?: readonly Tip[];
@@ -1876,6 +2309,23 @@ export interface ExplainEnvelopeOptions {
 	warnings?: readonly Warning[];
 }
 
+/**
+ * The host process environment, or an empty one where there is no host.
+ *
+ * A bare `Bun.env` default parameter is what a browser consumer of this module
+ * trips over (#312): the reference is evaluated on the first settings-ladder
+ * call, and `Bun` does not exist there. `typeof` is safe on an undeclared
+ * identifier, so the guard costs nothing and changes nothing under Bun — the
+ * ladder still reads the real environment, and a browser caller that never
+ * passes one gets the documented "no env tier" behavior rather than a crash.
+ *
+ * Only the offline analysis entry runs outside Bun; the other commands keep
+ * their `Bun.env` defaults because they open connections regardless.
+ */
+function hostEnv(): Record<string, string | undefined> {
+	return typeof Bun === "undefined" ? {} : Bun.env;
+}
+
 function settingsMeta(
 	format: ResolvedSetting<ExplainOutputFormat> | undefined,
 ): CommonSettingsMeta {
@@ -1891,7 +2341,7 @@ function settingsMeta(
  */
 export function resolveExplainFormat(
 	explicit: string | undefined,
-	env: Record<string, string | undefined> = Bun.env,
+	env: Record<string, string | undefined> = hostEnv(),
 	config: Record<string, string | undefined> = {},
 ): ResolvedSetting<ExplainOutputFormat> {
 	return resolveStringSetting(
@@ -2129,7 +2579,7 @@ function renderExplainText(
 		const bytes = data.input.bytes;
 		const pct = bytes === 0 ? 0 : (classified / bytes) * 100;
 		lines.push(
-			`tokens: ${data.tokens.length} token(s), ${classified}/${bytes} byte(s) classified (${pct.toFixed(1)}%), class provisional`,
+			`tokens: ${data.tokens.length} token(s), ${classified}/${bytes} byte(s) classified (${pct.toFixed(1)}%)`,
 		);
 		for (const t of data.tokens)
 			lines.push(`  ${span(t).padEnd(12)} ${t.class}`);