@tikoci/centrs 0.1.9-next.22 → 0.1.9-next.24

package/src/explain/highlight-projection.ts

@@ -45,21 +45,23 @@
  *   agreement (probes: "an abstention is not a disagreement").
  * - **parser-stop** — `error`. Measured over the committed slice this byte
  *   appears **at most once per script, always exactly one byte wide**, and on
- *   long-term 7.23.5 every byte after it is `none`: the device stops
+ *   long-term 7.23.8 every byte after it is `none`: the device stops
  *   classifying rather than recovering. Most of the slice's bytes sit in that
  *   tail, so a percentage that ignores it measures the device giving up.
- *   Stable 7.24.2 and development 7.25beta3 do classify again after the `error`
- *   in one run, which is why the report gives that a bucket of its own instead
- *   of asserting the rule (the counts live in the generated README block, not
- *   here, so they cannot go stale). The rule and its exception swapped builds
- *   with the #342 channel realignment; the shape of the claim did not.
+ *   Stable 7.24.5, testing 7.25rc2 and development 7.26beta1 do classify again
+ *   after the `error` in one run, which is why the report gives that a bucket
+ *   of its own instead of asserting the rule (the counts live in the generated
+ *   README block, not here, so they cannot go stale). The rule and its
+ *   exception swapped builds with the #342 channel realignment and held
+ *   through the #498 repin; the shape of the claim did not change.
  *
  * ## Upstream drift
  *
  * `DEVICE_CLASS_KIND` lists the 19 classes the phase-0 capture observed on
  * 7.23.2 / 7.24rc2 — and the #342 recapture found the SAME 19 on 7.24.2,
- * 7.23.5 and 7.25beta3, so the vocabulary has held across five builds and two
- * capture rounds. A class outside it is `"unknown"` — reported, never
+ * 7.23.5 and 7.25beta3, as did the #498 corpus sessions on 7.23.8, 7.24.5,
+ * 7.25rc2 and 7.26beta1, so the vocabulary has held across nine builds and
+ * three capture rounds. A class outside it is `"unknown"` — reported, never
  * silently folded into one of the four kinds — because a new upstream class is
  * exactly the drift the centrs-owned vocabulary exists to absorb, and guessing
  * its kind would hide it.

package/src/explain/operators.ts

@@ -1,12 +1,12 @@
 /**
  * The RouterOS operator surface, as the DEVICE describes it (#255).
  *
- * Every row here was scored by `bun run explain:probe:operators` on the three
- * builds the pinned corpus classes `complete` — stable 7.24.2 (which is also
- * the current testing build), long-term 7.23.5 and development 7.25beta3 — so
- * the operator axis and the token partition are measured on the same firmware
- * (#342). A fourth capture, 7.21.5, is kept as an **age anchor** rather than a
- * channel claim: it is the only live evidence that this surface behaves the
+ * Every row here was scored by `bun run explain:probe:operators` on the four
+ * builds the pinned corpus records a channel session for — stable 7.24.5,
+ * long-term 7.23.8, testing 7.25rc2 and development 7.26beta1 — so the
+ * operator axis and the token partition are measured on the same firmware
+ * (#342, #498). A fifth capture, 7.21.5, is kept as an **age anchor** rather
+ * than a channel claim: it is the only live evidence that this surface behaves the
  * same on a pre-7.23 branch. The reviewed slice is
  * `test/fixtures/explain/operators.json` → `sweep`, and
  * `test/unit/explain-operators.test.ts` asserts this table still equals it.
@@ -143,7 +143,8 @@ const OPERATORS: readonly RouterosOperator[] = [
 	// different operator, and arity is the only thing that separates them.
 	// Offline value-shape hints abstain on every such form: identical
 	// `(> …)` syntax can be `op` or `array` at runtime and `:parse` IL cannot
-	// distinguish them, so `op` lives only as a live `observedType` (#288).
+	// distinguish them; only `:typeof` can, and live explain never sends it,
+	// so `op` has no producer at all (#288, #225).
 	op(">", [1, 2], 5, "left", "relational", ">"),
 	op("=", [2], 5, "left", "relational", "="),
 	op("<=", [2], 5, "left", "relational", "<="),
@@ -366,24 +367,25 @@ function notOp(
  * The single version-dependent fact the sweep found.
  *
  * Every operator, arity, precedence level, associativity, `highlight` class and
- * op-axis row is identical on all four swept builds — 7.24.2, 7.23.5,
- * 7.25beta3 and the 7.21.5 age anchor — and identical is a measurement here,
- * not a reading: `buildSweep` diffs each of those axes per version, so a build
- * that re-ranked `->` would appear in `sweep.versionDifferences` rather than in
- * nobody's notes.
+ * op-axis row is identical on all five swept builds — 7.24.5, 7.23.8,
+ * 7.25rc2, 7.26beta1 and the 7.21.5 age anchor — and identical is a
+ * measurement here, not a reading: `buildSweep` diffs each of those axes per
+ * version, so a build that re-ranked `->` would appear in
+ * `sweep.versionDifferences` rather than in nobody's notes.
  *
  * The one row that moved is a RUNTIME semantic, not a lexer fact:
- * `:put ({2;1} > {1;2;3})` evaluates on 7.24.2 and 7.25beta3 and errors on both
- * long-term builds. So the offline lexer needs no version gate for operators —
+ * `:put ({2;1} > {1;2;3})` evaluates on 7.24.5, 7.25rc2 and 7.26beta1 and
+ * errors on both long-term builds. So the offline lexer needs no version gate for operators —
  * and anything that reports what a comparison MEANS does.
  */
 export const ARRAY_COMPARISON_NOTE =
-	"array comparison with `>` evaluates on 7.24.2 and 7.25beta3 and errors on " +
-	"7.23.5 and 7.21.5; the operator table itself is identical on all four. " +
-	"**It is not fixed on current long-term**: 7.23.5 is newer than the 7.23.3 " +
-	"this was first measured on and still errors, so the change rode the 7.24 " +
-	"line and was not backported. The two errors are not the same error: " +
-	"7.23.5 says `cannot compare if array is more than array` and 7.21.5 says " +
+	"array comparison with `>` evaluates on 7.24.5, 7.25rc2 and 7.26beta1 and " +
+	"errors on 7.23.8 and 7.21.5; the operator table itself is identical on all " +
+	"five. **It is not fixed on current long-term**: 7.23.8 is newer than the " +
+	"7.23.3 this was first measured on (and the 7.23.5 of #342) and still " +
+	"errors, so the change rode the 7.24 line and was not backported. The two " +
+	"errors are not the same error: 7.23.8 says `cannot compare if array is more " +
+	"than array` and 7.21.5 says " +
 	"`cannot compare if nothing is more than nothing`, so on 7.21.5 the " +
 	"`{2;1}` operands did not survive to the comparison at all. That is a " +
 	"RUNTIME difference either way — no version disagrees about what `>` is";

package/src/explain/pathresolve.ts

@@ -48,6 +48,15 @@
  *      filter` and `firewall/filter` under `/ip` are one form. If neither table
  *      knows the joined path, offline abstains and the following relative
  *      statements lose context certainty.
+ *   R14 An absolute bare path is navigation only when a shipped table names it
+ *      as a menu, exactly as R13 reads a relative one (#211). The verb-free
+ *      residue R9 and R12 leave (`/terminal/cuu`, a no-argument command neither
+ *      table lists) is a menu or a command, and offline cannot say which. So it
+ *      abstains, and the statements after it lose context certainty until an
+ *      absolute navigation re-establishes it. Absence is not evidence of a
+ *      command either: RouterOS accepts abbreviated menus (`/ip fire conn` is
+ *      `/ip/firewall/connection` in the device's own IL), so this does not read
+ *      the tables as a closed world.
  *
  * Verb-vs-menu identification is deliberately NOT decided here — offline cannot
  * tell `find` (verb) from a deeper menu without a schema (that is Q6). A
@@ -76,13 +85,15 @@
  *   - context-DEPENDENT — a relative statement (`add address=…`) resolves
  *     against the context, so it degrades.
  *
- * Three things make the context unknown, all cases where the statement might
+ * Four things make the context unknown, all cases where the statement might
  * have been navigation and offline cannot read where to:
  *   - a structural defect (the text is unreadable, so it may have been a nav),
  *   - a `/`-led statement whose leading run is unreadable (`/ip/$menu`, and
  *     equally the mixed spelling `/ip route/$menu`), which is a navigation to a
  *     computed menu as easily as it is a command,
- *   - a relative bare path that neither shipped structure table knows (#235).
+ *   - a relative bare path that neither shipped structure table knows (#235),
+ *   - an absolute bare path that neither table knows and no rule reads as a
+ *     command (#211, R14).
  * A dynamic-headed statement (`$x`, `[…]`, `(…)`) is context-NEUTRAL — it
  * evaluates a value and does not navigate — so it must NOT poison; that
  * distinction is the whole reason this lives here rather than in a caller,
@@ -457,6 +468,8 @@ function handsKnownContext(
 
 /** A re-constituted `[…]` command substitution (Q3). */
 export interface Resolution {
+	/** Index of the owning statement in `resolveStatements(text).statements`. */
+	owner: number;
 	/** Raw text inside the brackets. */
 	inner: string;
 	/** Context in force at the bracket, `/` when at document root. */
@@ -516,9 +529,22 @@ export function rangeForResolution(
 
 /** The canonical path of one statement in source order (Q4). */
 export interface StatementResolution {
+	/** Source ownership from traversal, independent of potentially widened spans. */
+	ownership?: {
+		/** Index of the statement whose scope body contains this statement. */
+		parent: number;
+		/** Body start as a UTF-16 offset in that parent's original text. */
+		bodyStart: number;
+	};
 	text: string;
 	/** Offline read this statement as menu navigation, not a command. */
 	isNav: boolean;
+	/**
+	 * A verb-free bare path that neither shipped table knows (#211, #235): it is
+	 * a menu navigation or a command, and offline cannot say which. `isNav` is
+	 * false, and the statements after it lose context certainty.
+	 */
+	maybeNav?: true;
 	/** Context in force BEFORE this statement. */
 	context: string;
 	/**
@@ -737,7 +763,7 @@ export function resolveDocument(text: string): DocumentAnalysis {
 	const resolutions: Resolution[] = [];
 	const top = locate(segmented, DOCUMENT_LOC, rootRange(text, segmented));
 	defects.push(...top.defects);
-	walk(top.units, "/", resolutions, 0, defects, true);
+	walk(top.units, "/", resolutions, 0, defects, true, { next: 0 });
 	return { resolutions, defects: mergeDefects(defects) };
 }
 
@@ -748,10 +774,14 @@ function walk(
 	blockDepth: number,
 	defects: Defect[],
 	contextCertain: boolean,
+	statements: { next: number },
 ): void {
 	let ctx = context;
 	let certain = contextCertain;
 	for (const unit of units) {
+		// Count navigation and unreadable statements too, exactly as the Q4 walk
+		// does. Brackets in one unit (including nested brackets) share its owner.
+		const owner = statements.next++;
 		const { text, loc, range } = unit;
 		// R4 — a menu-navigation statement moves the document context.
 		const nav = menuNavPath(text, ctx, range);
@@ -772,9 +802,9 @@ function walk(
 			certain = false;
 			continue;
 		}
-		// #235 — a relative bare-word that abstained (neither table) poisons
+		// #235, #211 — a bare path that abstained (neither table) poisons
 		// downstream context, so the next relative statement cannot fabricate.
-		const poisonAbstention = isAbstainedRelativeNav(text, ctx, range);
+		const poisonAbstention = isAbstainedNav(text, ctx, range);
 		// R3 — the statement's own path is the context its brackets see.
 		const stmtCtx = statementPath(text, ctx, range);
 		// Derived BEFORE the poison, from the certainty in force at this statement:
@@ -785,7 +815,7 @@ function walk(
 			? false
 			: handsKnownContext(text, certain, range);
 		if (isUnreadableAbsolute(text) || poisonAbstention) certain = false;
-		collectBrackets(range, stmtCtx, 0, out, defects, stmtCertain, loc);
+		collectBrackets(range, stmtCtx, 0, out, defects, stmtCertain, loc, owner);
 		// R5 — block bodies inherit the context in force here.
 		for (const block of scopeBlocksIn(range)) {
 			if (blockDepth >= MAX_DEPTH) {
@@ -804,7 +834,15 @@ function walk(
 				bodyRange(range, block),
 			);
 			defects.push(...body.defects);
-			walk(body.units, stmtCtx, out, blockDepth + 1, defects, stmtCertain);
+			walk(
+				body.units,
+				stmtCtx,
+				out,
+				blockDepth + 1,
+				defects,
+				stmtCertain,
+				statements,
+			);
 		}
 	}
 }
@@ -828,10 +866,16 @@ function walkStatements(
 	blockDepth: number,
 	defects: Defect[],
 	contextCertain: boolean,
+	ownership?: StatementResolution["ownership"],
 ): void {
 	let ctx = context;
 	let certain = contextCertain;
+	const push = (statement: StatementResolution): void => {
+		if (ownership !== undefined) statement.ownership = ownership;
+		out.push(statement);
+	};
 	for (const unit of units) {
+		const parent = out.length;
 		const { text, span, range } = unit;
 		const nav = menuNavPath(text, ctx, range);
 		if (nav !== null) {
@@ -840,7 +884,7 @@ function walkStatements(
 			// therefore re-establishes certainty.
 			const relative = !trimAscii(text).startsWith("/");
 			if (relative && !certain) {
-				out.push({
+				push({
 					text,
 					isNav: true,
 					context: ctx,
@@ -851,7 +895,7 @@ function walkStatements(
 				});
 				continue;
 			}
-			out.push({
+			push({
 				text,
 				isNav: true,
 				context: ctx,
@@ -868,7 +912,7 @@ function walkStatements(
 		// BEEN a navigation, so what the context now is becomes unknown.
 		const defectReason = structuralDefectIn(range);
 		if (defectReason !== null) {
-			out.push({
+			push({
 				text,
 				isNav: false,
 				context: ctx,
@@ -880,18 +924,19 @@ function walkStatements(
 			certain = false;
 			continue;
 		}
-		// #235 — a relative bare-word that abstained (neither table) poisons
+		// #235, #211 — a bare path that abstained (neither table) poisons
 		// downstream context. Capture before the push so the current statement's
 		// own `contextCertain` stays true while the following statements lose it.
-		const poisonAbstention = isAbstainedRelativeNav(text, ctx, range);
+		const poisonAbstention = isAbstainedNav(text, ctx, range);
 		// Q14 C3b — the cascade. A statement that CONSUMES the context cannot be
 		// resolved against a value the resolver has already admitted it lost.
 		// Applied to the RESOLUTION, not ahead of it, so a statement that would
 		// have refused on its own terms keeps its own — more specific — reason.
 		const resolved = canonicalPath(text, ctx, range);
-		out.push({
+		push({
 			text,
 			isNav: false,
+			...(poisonAbstention ? { maybeNav: true as const } : {}),
 			context: ctx,
 			...(resolved.path !== null &&
 			!certain &&
@@ -933,6 +978,7 @@ function walkStatements(
 				blockDepth + 1,
 				defects,
 				bodyCertain,
+				{ parent, bodyStart: block.start },
 			);
 		}
 	}
@@ -981,6 +1027,12 @@ function walkStatements(
  * contradiction R9 closed — and worse than before, since the two modules would
  * now disagree CONFIDENTLY rather than one of them refusing. The same test pins
  * the invariant for both rules.
+ *
+ * R14 (#211) — "absence from both still abstains" was not true here until R14.
+ * A verb-free path neither table knows still came back as a navigation, so
+ * `/terminal/cuu` moved the context and the `print` after it resolved
+ * confidently to `/terminal/cuu/print`. Now it abstains the way R13's relative
+ * path does: the statement is not navigation, and what follows loses certainty.
  */
 function menuNavPath(
 	text: string,
@@ -999,6 +1051,19 @@ function menuNavPath(
 		const reading = readRelativeBare(text, ctx, range);
 		return reading?.kind === "nav" ? reading.path : null;
 	}
+	const reading = readAbsoluteBare(trimmed);
+	return reading?.kind === "nav" ? reading.path : null;
+}
+
+/**
+ * How an ABSOLUTE bare-path statement reads (R9, R12, R14).
+ *
+ * The `/`-led twin of {@link readRelativeBare}, with the same three answers. A
+ * run carrying a vocabulary verb (R9) or naming a published command (R12) is a
+ * COMMAND: `null`. Otherwise it is verb-free, and a shipped table decides: a
+ * known menu is `nav`, and a path neither table knows is `abstain` (R14).
+ */
+function readAbsoluteBare(trimmed: string): BarePathReading | null {
 	if (/[=[({"$]/.test(trimmed)) return null;
 	const tokens = asciiWords(trimmed);
 	if (
@@ -1016,7 +1081,11 @@ function menuNavPath(
 	if (segments.some((segment) => VERBS.has(segment))) return null;
 	// R12 — the same segments, against the published command axis.
 	if (commandVerbIndex(segments) !== null) return null;
-	return joinPath("/", tokens.join("/"));
+	// R14 (#211) — the verb-free residue. Presence in a table decides, as R13
+	// decides a relative one; absence abstains rather than navigate.
+	return isKnownMenuPath(segments)
+		? { kind: "nav", path: joinPath("/", tokens.join("/")) }
+		: { kind: "abstain" };
 }
 
 /**
@@ -1036,13 +1105,13 @@ function menuNavPath(
  * they can drift, and a drift there is silently either a lost navigation or a
  * poisoned document.
  */
-type RelativeBareReading = { kind: "nav"; path: string } | { kind: "abstain" };
+type BarePathReading = { kind: "nav"; path: string } | { kind: "abstain" };
 
 function readRelativeBare(
 	text: string,
 	ctx: string,
 	range: MaskedRange,
-): RelativeBareReading | null {
+): BarePathReading | null {
 	const trimmed = trimAscii(text);
 	if (
 		trimmed.length === 0 ||
@@ -1074,17 +1143,22 @@ function readRelativeBare(
 }
 
 /**
- * #235 — does `text` look like a relative menu navigation that ABSTAINED?
+ * #235, #211 — does `text` look like a menu navigation that ABSTAINED, in
+ * either spelling?
  *
  * Presence in a table → nav; absence → abstain → poison downstream, so the
  * next relative statement cannot resolve against a context that may have moved.
  */
-function isAbstainedRelativeNav(
+function isAbstainedNav(
 	text: string,
 	ctx: string,
 	range: MaskedRange,
 ): boolean {
-	return readRelativeBare(text, ctx, range)?.kind === "abstain";
+	const trimmed = trimAscii(text);
+	const reading = trimmed.startsWith("/")
+		? readAbsoluteBare(trimmed)
+		: readRelativeBare(text, ctx, range);
+	return reading?.kind === "abstain";
 }
 
 function canonicalPath(
@@ -1214,6 +1288,7 @@ function collectBrackets(
 	defects: Defect[],
 	contextCertain: boolean,
 	loc: Loc,
+	owner: number,
 	inLiteral = false,
 ): void {
 	const { masked, start: lo, end: hi } = range;
@@ -1240,6 +1315,7 @@ function collectBrackets(
 				defects,
 				contextCertain,
 				nest(loc, i + 1 - lo, loc.fallback),
+				owner,
 			);
 			i = strEnd;
 			continue;
@@ -1259,6 +1335,7 @@ function collectBrackets(
 					defects,
 					contextCertain,
 					nest(loc, i + 1 - lo, loc.fallback),
+					owner,
 					true,
 				);
 			i = end;
@@ -1273,6 +1350,7 @@ function collectBrackets(
 		const inner = masked.slice(innerAt, innerEnd);
 		// The span covers the whole `[…]`, closing bracket included.
 		const resolution: Resolution = {
+			owner,
 			...resolveInner(inner, ctx, depth, contextCertain),
 			span: spanIn(loc, i - lo, Math.min(end + 1, hi) - lo),
 			innerSpan: spanIn(loc, innerAt - lo, innerEnd - lo),
@@ -1289,6 +1367,7 @@ function collectBrackets(
 			defects,
 			nestedCertainty(resolution, contextCertain),
 			nest(loc, innerAt - lo, loc.fallback),
+			owner,
 		);
 		i = end;
 	}
@@ -1346,6 +1425,7 @@ function scanInterpolations(
 	defects: Defect[],
 	contextCertain: boolean,
 	loc: Loc,
+	owner: number,
 ): void {
 	const { text, start: lo, end: hi } = range;
 	for (let i = lo; i < hi - 1; i++) {
@@ -1367,6 +1447,7 @@ function scanInterpolations(
 		// Span the `$[…]` from its sigil through the closing bracket; `innerSpan`
 		// is the two-byte-in start that difference makes non-derivable.
 		const resolution: Resolution = {
+			owner,
 			...resolveInner(maskedInner, ctx, depth, contextCertain),
 			inner,
 			span: spanIn(loc, i - lo, Math.min(end + 1, hi) - lo),
@@ -1382,6 +1463,7 @@ function scanInterpolations(
 			defects,
 			nestedCertainty(resolution, contextCertain),
 			nest(loc, innerAt - lo, loc.fallback),
+			owner,
 		);
 		i = end;
 	}
@@ -1435,7 +1517,7 @@ function resolveInner(
 	ctx: string,
 	depth: number,
 	contextCertain: boolean,
-): Omit<Resolution, "span" | "innerSpan"> {
+): Omit<Resolution, "span" | "innerSpan" | "owner"> {
 	const absolute = inner.startsWith("/");
 	const klass = classify(inner, absolute, depth);
 	if (klass === "cli-prompt-artifact")

package/src/explain/quoted-string.ts

@@ -112,6 +112,31 @@ function escapeLength(text: string, at: number): 2 | 3 {
 // (skip vs validate) and whether they skip comment spans.
 // ---------------------------------------------------------------------------
 
+/**
+ * Whether the byte after a string-phase `$` makes it a device error.
+ *
+ * Inside a string a `$` must start an interpolation: a name
+ * (`"$v"`, `"$v_x"` is `$v` then `_x`), `$"…"`, `$(…)` or `$[…]`. Every other
+ * follower is `syntax error` at that byte on CHR 7.24.5 and 7.23.8, swept with
+ * `:parse` on a stored script source: `"a$ b"`, `"$-"`, `"$."`, `"$,"`, `"$_"`,
+ * `"$;"`, `"$="`, `"${"`, `"$)"`, `"$\n"`, a TAB, and the same inside
+ * `where`, an array, a group and a nested `$[…]` string (#506). A literal
+ * dollar is `\$`.
+ *
+ * `$$` abstains: the device does not stop at the second `$` (`"$$"` is
+ * rejected at the closing quote), so what it reads there is not known.
+ *
+ * `$"` abstains. The device reads it as a quoted variable name (`"a$"v""` is
+ * `(. a $v)`), so the next `"` does not close the string, and every scanner in
+ * `explain` closes it there; `"a$"` is a device rejection this cannot see. A
+ * non-ASCII stand-in (`SUB`) abstains too: the byte it replaced is #371's.
+ */
+function invalidStringSigil(next: string | undefined): boolean {
+	if (next === undefined || next === '"' || next === "$" || next === "\x1a")
+		return false;
+	return !/[A-Za-z0-9[(]/.test(next);
+}
+
 /**
  * One step of the shared frame machine. Owns the depth guard, the `top` read,
  * and the phase dispatch (`"` vs code) so callers cannot drift on them.
@@ -125,6 +150,7 @@ function stepFrame(
 	frames: string[],
 	onStringEscape: (at: number) => number | Defect,
 	maxFrameDepth: number = MAX_STRING_FRAME_DEPTH,
+	validateSigil = false,
 ): number | Defect {
 	if (frames.length > maxFrameDepth) return 0;
 	const top = frames[frames.length - 1] as string | undefined;
@@ -139,6 +165,8 @@ function stepFrame(
 			frames.push(text[i + 1] as string);
 			return 2;
 		}
+		if (c === "$" && validateSigil && invalidStringSigil(text[i + 1]))
+			return { code: "bad-string-variable", start: i, end: i + 2 };
 		return 1;
 	}
 	if (c === '"') {
@@ -303,12 +331,19 @@ export function walkStringEscapes(
 				continue;
 			}
 		}
-		const res = stepFrame(text, i, frames, (at) => {
-			const step = stringEscapeValidated(text, at);
-			if (collectEscapes && typeof step === "number")
-				escapes.push({ start: at, end: at + step });
-			return step;
-		});
+		const res = stepFrame(
+			text,
+			i,
+			frames,
+			(at) => {
+				const step = stringEscapeValidated(text, at);
+				if (collectEscapes && typeof step === "number")
+					escapes.push({ start: at, end: at + step });
+				return step;
+			},
+			MAX_STRING_FRAME_DEPTH,
+			true,
+		);
 		if (typeof res !== "number") return { escapes, defects: [res] };
 		if (res === 0) break;
 		i += res;