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

package/commands/explain/examples.md

@@ -483,7 +483,8 @@ REST body; the comment text is never rendered as an operand.
 
 The CHR assertion grounds the wider placement rule on the requested RouterOS
 channel via `/console/inspect request=highlight` plus `:parse`: unquoted `#`
-inside brace arrays and parenthesized expressions is a hard error; the first
+inside brace arrays and parenthesized expressions is a hard error, except at
+column 0 inside an array (example 37); the first
 non-space `#` in `do`, `else`, `foreach do`, and `on-event` bodies that are
 themselves in a statement context is a comment — the same `do={ # c` nested
 inside an array is an array and `#` is an error (placement table, #249), while
@@ -700,3 +701,261 @@ envelope would otherwise have to derive the name/value boundary from
 The same command also shows the two `=` bytes staying apart: the one in
 `($x = 1)` is a comparison and comes back `operator`, decided by fill order
 rather than by a scan for the byte.
+
+### 33. A space for the `=` is not an empty argument list
+
+```bash
+centrs explain '/ip/firewall/layer7-protocol add comment "something" regexp 1.1' --json
+```
+
+RouterOS accepts this as `comment="something" regexp=1.1`: `:parse` lowers both
+spellings to the same IL, and `highlight` marks each gap `syntax-obsolete`.
+Which word is an argument name is per-command schema, so offline publishes
+neither reading. The statement stays `resolved` on
+`/ip/firewall/layer7-protocol add`, `command.args` is absent, `arguments.read`
+is `false` with a `why` naming `` `comment "something"` ``, and
+`transport.classification` stays `"unknown"`.
+
+`data.verdict` is `warn`, with one
+`explain/canonicalizer/possible-spaced-argument` **warning** per pair,
+spanning `comment "something"` and `regexp 1.1`. Each says to write the `=`.
+The warning needs a value that cannot be a flag: `/interface set ether1 name x`
+also abstains but does not warn, because `/interface print detail
+without-paging` is the same shape and is two flags
+(`detail=true;without-paging=true`). The `=` spelling still reads both
+arguments, and a script body may drop its `=` too:
+`/system/script add name=beep source { :beep }` is the `source={ :beep }` body,
+not an invalid brace.
+
+### 34. An unlisted bare path does not become a menu
+
+```bash
+centrs explain $'/terminal/cuu\nprint\nadd name=x' --json
+```
+
+`/terminal/cuu` is a no-argument command that neither the menu table nor the
+command catalog lists. `/ip fire conn` has the same shape and is navigation:
+RouterOS accepts abbreviated menus. CHR 7.24.5 `:parse` confirms both, so a
+table miss cannot decide between a menu and a command.
+
+The first statement stays `ambiguous`. The two after it are `unknown`
+(`context lost to an earlier unreadable statement`, `contextCertain: false`),
+with no `command` and no `transport`, where they used to resolve to an
+invented `/terminal/cuu/print` and `/terminal/cuu/add`. On the device they are
+`bad command name print` and `bad command name add` at the root.
+`structure.containsWrite` is `unknown` and `data.verdict` is `warn`. A known
+absolute navigation recovers the context: in
+`/terminal/cuu`, `/ip address`, `print`, the last statement resolves to `print`
+at `/ip/address` again.
+
+### 35. A brace after a command is its argument, not a menu block
+
+```bash
+centrs explain '/system/script add name beep source { :beep }' --json
+```
+
+`/menu { … }` opens a menu block only when the words before the brace name a
+menu. Here `add` is a command, so the brace is the value of `source` with the
+`=` left out. CHR 7.22.1 and 7.24.5 `:parse` give the same IL as
+`source={ :beep }`.
+
+`data.structure.statements` has one statement, `/system/script add`, whose
+span covers the whole input. `:beep` is no longer published as a second
+top-level statement, which RouterOS never runs. `data.verdict` is `warn`, from
+the `possible-spaced-argument` diagnostic on `source { :beep }`.
+
+RouterOS accepts any unique prefix of an argument name. An abbreviation that
+can only stand for a script-valued name keeps its body in either spelling:
+`sour { :beep }`, `down-scr { :beep }` and `o={ :beep }` lower to `source=`,
+`down-script=` and `on-event=` on CHR 7.24.5 and 7.23.8. Abbreviating the first
+segment (`down={ :beep }` for `down-script`) is accepted on the device too, but
+offline still reports `invalid-command-brace`. Every word is a prefix of some
+`<word>-script`, so telling it from `comment={ :beep }` needs the command's
+argument list.
+
+A brace straight after a command is a device error, and offline now reports it.
+`/system/script add { :beep }`, `/ip/route/print {1;2}` and
+`/system/reboot { :beep }` each get `invalid-command-brace` and `data.verdict`
+`fail`. A run that names no command still opens a block, so
+`/system script { print }` is navigation to `/system/script` followed by
+`print`.
+
+### 36. A brace in a `where` clause is an array value
+
+```bash
+centrs explain '/ip address print where interface in {"ether1";"ether2"}' --json
+```
+
+A `where` clause is expression context, so the brace is the array operand of
+`in`. CHR 7.24.5 and 7.23.8 `:parse` lower it to
+`(in $interface ether1;ether2)`. `data.verdict` is `pass`, so `centrs execute`
+runs this read. Before #502 its offline stage refused it with
+`invalid-command-brace`. `data.values.occurrences` holds the array and its two
+string members, the same three records as
+`where interface in ("ether1","ether2")`.
+
+The brace is also a value after `~`, `<`, `>`, `<=` and `>=`, on the left of an
+operator (`where {"ether1"} in interface`), and after `!interface=` or `"a"=`.
+
+After `<name>=`, `<name>!=` or `<name>==`, spaced or not, the device reads the
+value with that property's parser and rejects the brace. Two examples are
+`where interface={"ether1"}` (`expected interface value`) and
+`where disabled={"y"}` (`expected yes or no`). Offline keeps
+`invalid-command-brace` at the `{` there. The device does this only for a
+property the menu knows: `where foo-bar={"y"}` parses. Offline cannot tell
+property names apart without a per-menu list, so it reports that one too.
+
+### 37. A column-0 `#` line inside an array is a comment
+
+```bash
+centrs explain ':local z {a=1;
+# c
+b=2}' --json
+```
+
+`data.verdict` is `pass`. `data.spans` holds a `comment` span over `# c`, and
+`data.values.occurrences` holds the array and its two members `a` and `b`. CHR
+7.24.5 and 7.22.1 `:parse` lower it to `value=a=1;b=2`. Before #503, offline
+failed it with `invalid-hash` at the `#`.
+
+The rule holds at any depth (`{a={⏎# c⏎1}}`) and in argument values
+(`:foreach i in={1;⏎# c⏎2} do={:put $i}`). It needs column 0: an indented `#`
+(`{a=1;⏎  # c⏎b=2}`), and one after `{`, a value or `;` on the same line, keep
+`invalid-hash` at the `#`. A `#` directly inside `( … )` stays an error too. A
+comment-only array, `:local z {⏎# c⏎}`, fails like `:local z {}`: both are empty
+arrays, which the device rejects (#511, example 38).
+
+### 38. An empty array value and a misplaced `;` are rejected
+
+```bash
+centrs explain ':local z {}' --json
+```
+
+`data.verdict` is `fail` with `explain/canonicalizer/empty-group` over `{}`. CHR
+7.24.5 and 7.23.8 `:parse` answer `syntax error (line 1 column 12)`, the byte
+after the brace. The same holds for `:put {}`, `:return {}`, `[:len {}]` and
+`:foreach i in={} do={…}`. A nested `{}` (`{1;{}}`), one in parentheses
+(`({})`), `where … in {}` and a body (`do={}`, `:execute {}`) parse and pass.
+
+`:local z {1⏎;2}` fails with `misplaced-separator` at the `;`: a `;` needs an
+element before it on its line. `{1;}` and `{1⏎2}` pass.
+
+### 39. An expression with a missing operand is rejected
+
+```bash
+centrs explain ':put (1 +)' --json
+```
+
+`data.verdict` is `fail` with `explain/canonicalizer/missing-operand` at the
+`+`. The device answers `syntax error (line 1 column 11)`, at the `)`. `()`
+fails with `empty-group`, and `(1; 2)` and `(1⏎+ 2)` fail with
+`misplaced-separator`. `(1 2)`, `(- 1)` and `(1 + -2)` pass. Inside a query,
+`where (comment=+)` passes: the device reads that value with the property's
+parser.
+
+### 40. A `@` in a command word is rejected
+
+```bash
+centrs explain '[admin@MikroTik] > /ip address print' --json
+```
+
+`data.verdict` is `fail` with `explain/canonicalizer/invalid-at-sign` at the
+`@`. The device answers `syntax error (line 1 column 7)`, the same byte. This
+is a pasted console prompt. `:put a@b` and `comment=a@b` pass, because a `@` is
+a value byte in an argument.
+
+### 41. A named comparison brace inside a `[find where …]` is rejected
+
+```bash
+centrs explain ':put [/ip address find where interface={"x"}]' --json
+```
+
+`data.verdict` is `fail` with `explain/canonicalizer/invalid-command-brace` at
+the `{`, as at the top level (example 36). The device answers
+`expected interface value (line 1 column 40)`. `where (interface={"x"})` fails
+the same way, and `[find where interface in {"x"}]` passes.
+
+### 42. A stray top-level `}` ends the script, and the rest is discarded
+
+```bash
+centrs explain ':put 1};:put 2' --json
+```
+
+`data.verdict` is `warn` with `explain/canonicalizer/discarded-close` over the
+`}` and everything after it. CHR 7.24.5 and 7.23.8 accept the script and lower
+it to `(evl /putmessage=1)`: the device stops reading at a `}` or `]` that closes
+nothing at the top level, so `:put 2` never runs and
+`/system identity set name=a}` sets `a`. `data.structure` reads only the
+prefix. A stray close inside an open group (`:put (1})`, `{:put 1]}`) and any
+stray `)` are still rejections and still fail with `unbalanced-close`. The
+execute gate refuses this warning (`commands/execute/examples.md` V9).
+
+### 43. A variable name is letters and digits
+
+```bash
+centrs explain ':local a_b 1' --json
+```
+
+`data.verdict` is `fail` with `explain/canonicalizer/invalid-name` at the `_`.
+The device answers `expected end of command (line 1 column 9)`, the same byte.
+`:global`, `:set`, `:for` and `:foreach` read the name the same way, and
+`:local $a` and `:local (a)` fail at their first byte. `:local "a_b"`,
+`:local 1a`, `:foreach a,b in={1} do={}` and `:local name=x value=1` pass.
+
+### 44. A `$` must start a variable
+
+```bash
+centrs explain ':put "a$ b"' --json
+```
+
+`data.verdict` is `fail` with `explain/canonicalizer/bad-string-variable` over
+the `$` and the space after it. The device answers `syntax error (line 1 column 9)`, at the space. Outside
+a string, `:put $_` fails with `invalid-variable` the same way. `"$v_x"` (which
+is `$v` then `_x`), `"\$ x"`, `"$(1)"` and `$"a b"` pass. `"a$"` also passes,
+although the device rejects it: it reads `$"` as the start of a quoted name, and
+offline's string scanners end the string there, so offline abstains.
+
+### 45. Nothing may be glued to a closed token
+
+```bash
+centrs explain ':if (true) do={:put 1}else={:put 2}' --json
+```
+
+`data.verdict` is `fail` with `explain/canonicalizer/glued-token` at the `e`.
+The device answers `expected end of command (line 1 column 23)`. The same rule
+rejects `:put "a"b`, `$v.b`, `(1)(2)`, `[:len a]b`, `src-address=$v/24` and a
+bare word run into a `"`, `$` or bracket (`:put a"b"`, `name=a$v`). Inside
+`where` and `find`, and inside a group, the rule does not apply (`where
+comment="a"b` and `("a"b)` parse). A command argument whose property parser
+takes the glued part also passes: `dst-address-list=!"my list"` and
+`dst-port=80,"443"`.
+
+### 46. Statement ids and source ownership
+
+```bash
+centrs explain ':if (true) do={ :foreach i in={1;2} do={ :put $i } } else={ :put 0 }; :put 3' --json
+```
+
+The statements keep discovery order and have ids `s0` through `s4`.
+The `foreach` (`s1`) has `parent: "s0"`; its `put` (`s2`) has `parent: "s1"`;
+the `else` body's `put` (`s3`) has `parent: "s0"`. The final `put` (`s4`) has
+no parent. The published `do` and `else` blocks both have `owner: "s0"`;
+`s1` and `s2` share `block: 0`, and `s3` has `block: 1`. A `[find]` inside a
+body names that body's statement as its `owner`. Links describe source
+ownership; binding and execution-context claims remain separate (#507).
+
+### 47. A stored script stays opaque
+
+```bash
+centrs explain '/system/script/add name=proof source={ :local x 1; :put $x }; :put 2' --json
+```
+
+Only the installing command (`s0`) and final `put` (`s1`) appear in
+`statements[]`; neither has a parent, and `blocks[]` stays empty. The deferred
+body's local and `put` are not exposed as statements. Scheduler `on-event=`
+and Netwatch `down-script=` have the same structural boundary.
+
+The CHR controls in `test/integration/explain-structure.test.ts` parse the
+scope examples and compare stored-script creation, explicit `run`, and an
+immediate `:do` body. Those are test operations on disposable CHR; explain
+itself never executes the analyzed input.

package/docs/CONSTITUTION.md

@@ -58,6 +58,10 @@ is unsafe the offline stage is what keeps the gate from degrading to nothing. A
 clean offline pass is **necessary, never sufficient** — `explain` publishes
 `runtimeAcceptance: "not-proven"` for exactly this reason. An offline `warn` is
 an ABSTENTION and passes through to the device stage; only a `fail` rejects.
+The one exception is `discarded-close`: a stray top-level `}` or `]` that the
+device accepts and then silently stops reading at (#504). It is a warning,
+because nothing is rejected, and the gate refuses it by code
+(`src/offline-gate.ts`), because the device would run a different script.
 
 `meta.validation.stages[]` reports what each stage concluded, including a stage
 that was skipped and why. A reader must always be able to tell "the device

package/docs/MATRIX.md

@@ -182,17 +182,26 @@ Wire, auth, TCP/UDP, and CI caveats live in `commands/btest/README.md` and the
 
 ## Current priority
 
-**First: the CMR track** (maintainer decision 2026-10-12 on
-[#441](https://github.com/tikoci/centrs/issues/441)). Done: `execute --cmr`
+**First: `explain`** (maintainer decision 2026-10-16 on
+[#90](https://github.com/tikoci/centrs/issues/90)). In order: make the
+published offline readings honest (#350, #211), give the result a statement
+tree, then the live probe foundation (#491). Then use those probes to
+ground #351, #358 and #371, and finish live (#492 → #236 closeout). The
+plan, and what is deliberately out of this run, is the 2026-10-16 plan
+comment on #90. It is step 3 of the validation track below.
+
+**The CMR track is paused until RouterOS 7.26beta2** (maintainer decision
+2026-10-16). It was first from the 2026-10-12 decision on
+[#441](https://github.com/tikoci/centrs/issues/441). Done: `execute --cmr`
 (#450), which runs one validated command on CMR clients through their
 controller. The contract is in
 [`commands/execute/README.md` → CMR](../commands/execute/README.md#cmr-clients-through-their-controller---cmr),
 with examples CMR0–CMR15. Also done: the fleet blast-radius gate for
 controller fleet commands run with plain `execute` or `api` (#453), with
 examples CMR16–CMR18 and api CMR1. The feature map of CMR against centrs is
-on #441 (2026-10-13). Next is the read-only slice of #449 (a `devices` view
-of members and a default controller). Deferred: CDB linkage (#449) and `retrieve --cmr` (#441).
-Live `explain` resumes after this.
+on #441 (2026-10-13). When it resumes, next is the read-only slice of #449 (a
+`devices` view of members and a default controller). Deferred: CDB linkage
+(#449) and `retrieve --cmr` (#441).
 
 **The native-api / NDJSON line** (maintainer decision on
 [#396](https://github.com/tikoci/centrs/issues/396), 2026-10-07): agents in the
@@ -230,16 +239,19 @@ producers owned with #225. REST and native-api cells advance only when their
 applicable examples pass on CHR via `bun run test:integration`.
 
 Open offline follow-ups remain explicit but do not reopen the verified baseline.
-Issue #211 retains the fail-closed unlisted-path decision; #272 owns
+Issue #211 made an unlisted absolute bare path abstain (rule F, R14); rule
+P's closed-world reading is still not adopted (#372). #272 owns
 non-authoritative `.scratch/` citation cleanup. #350 (the broad optional `=`,
 schema-dependent and so belonging to step 3), #351 (an unresolvable menu that
 abstains at 2-deep nesting but hard-fails at 3-deep) and #355 (`'` is not a
 RouterOS token — a false ACCEPT the corpus join cannot see) are bounded analyzer
-defects that step 2 now surfaces through the `execute`/`api` gate. #336 and #342 are complete: the
-corpus is repinned to three *complete* builds (long-term 7.23.5, stable 7.24.2,
-development 7.25beta3), and the operator sweep and highlight slice are re-swept
-onto those same builds — plus 7.21.5 retained as an age anchor — so the operator
-axis and the token partition are scored on the same firmware. The #335
+defects that step 2 now surfaces through the `execute`/`api` gate. #336, #342 and #498 are complete: the
+corpus is pinned to schema 5, with one recorded session per release channel
+(long-term 7.23.8, stable 7.24.5, testing 7.25rc2, development 7.26beta1) read
+through `scripts/corpus-db.ts`. The highlight slice is cut from those sessions
+and gated in CI, and the operator sweep is re-run on the same builds — plus
+7.21.5 retained as an age anchor — so the operator axis and the token partition
+are scored on the same firmware. The #335
 source refresh pins both architectures of those versions beside the 7.10.2 /
 7.16 history anchors and accepts the current CLI-Reference drift. Issue #223 is
 a separate MCP response migration. If live evidence finds a wrong offline

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tikoci/centrs",
-	"version": "0.1.9-next.22",
+	"version": "0.1.9-next.23",
 	"main": "src/index.ts",
 	"module": "src/index.ts",
 	"repository": {
@@ -103,11 +103,14 @@
 		"explain:catalog": "bun run scripts/gen-explain-catalog.ts",
 		"explain:catalog:check": "bun run scripts/gen-explain-catalog.ts --check",
 		"explain:corpus-census": "bun run scripts/explain-corpus-census.ts",
+		"explain:conformance": "bun run scripts/explain-conformance.ts",
+		"explain:conformance:check": "bun run scripts/explain-conformance.ts --check",
 		"explain:highlight-agreement": "bun run scripts/explain-highlight-agreement.ts",
 		"explain:highlight-agreement:check": "bun run scripts/explain-highlight-agreement.ts --check",
 		"explain:highlight-agreement:readme": "bun run scripts/explain-highlight-agreement.ts --readme",
 		"explain:highlight-agreement:readme:check": "bun run scripts/explain-highlight-agreement.ts --readme --check",
 		"explain:highlight-slice": "bun run scripts/explain-highlight-slice.ts",
+		"explain:highlight-slice:check": "bun run scripts/explain-highlight-slice.ts --check",
 		"explain:menus": "bun run scripts/gen-explain-menus.ts",
 		"explain:operator-census": "bun run scripts/explain-operator-census.ts",
 		"explain:operator-census:check": "bun run scripts/explain-operator-census.ts --check",

package/src/explain/args.ts

@@ -87,7 +87,7 @@ import {
 } from "./segment.ts";
 
 /** A RouterOS argument name: bare word, optionally dotted (`.id`, `.proplist`). */
-const ARGUMENT_NAME = /^\.?[A-Za-z][A-Za-z0-9._-]*$/;
+export const ARGUMENT_NAME = /^\.?[A-Za-z][A-Za-z0-9._-]*$/;
 
 /** What one argument token is. */
 export type ArgumentKind = "attribute" | "positional" | "query";
@@ -327,6 +327,12 @@ interface WalkOptions {
 	 * see {@link braceSlotTakesArray}.
 	 */
 	directiveVerb?: string;
+	/**
+	 * Where a command's top-level `where` positional ends, set by the walk itself
+	 * once it reads one. From there on a brace is an expression value
+	 * (see {@link comparesNamedValue}).
+	 */
+	whereAt?: number;
 }
 
 /** How deep member scanning descends before it stops and keeps only the shape. */
@@ -363,7 +369,11 @@ function braceOpensArray(
 	options: WalkOptions,
 ): boolean {
 	const verb = options.directiveVerb;
-	if (verb === undefined) return false;
+	if (verb === undefined)
+		return (
+			options.whereAt !== undefined &&
+			!comparesNamedValue(text, at, options.whereAt)
+		);
 	const owner = braceValueOwner(text, tokenStart, at);
 	if (owner === undefined) return false;
 	return braceSlotTakesArray(
@@ -390,6 +400,7 @@ function* walkArguments(
 	let i = Math.max(0, from);
 	// How many positionals have been read, which is the NEXT positional's index.
 	let positionals = 0;
+	let walk = options;
 	while (i < text.length) {
 		// The MASKED view decides whitespace, because `maskComments` blanks a
 		// continuation comment that `text` still spells with a `#`. Reading `text`
@@ -412,7 +423,7 @@ function* walkArguments(
 			i += continuation;
 			continue;
 		}
-		const token = scanToken(text, structural, i, positionals, options);
+		const token = scanToken(text, structural, i, positionals, walk);
 		if (typeof token === "string") {
 			yield token;
 			return;
@@ -430,7 +441,7 @@ function* walkArguments(
 		// the refusal exists to prevent. Shape only, never a value.
 		const read =
 			token.why === undefined
-				? readToken(text, structural, i, token.end, options)
+				? readToken(text, structural, i, token.end, walk)
 				: undecidedToken(text, i, token.end, token.why);
 		if (typeof read === "string") {
 			if (options.tolerant !== true) {
@@ -446,6 +457,13 @@ function* walkArguments(
 			continue;
 		}
 		if (read.kind === "positional") positionals++;
+		if (
+			read.kind === "positional" &&
+			read.text === "where" &&
+			walk.directiveVerb === undefined &&
+			walk.whereAt === undefined
+		)
+			walk = { ...walk, whereAt: token.end };
 		yield read;
 		i = token.end;
 	}
@@ -1661,13 +1679,51 @@ export function lexValueAnchors(
 	return { complete: true, anchors };
 }
 
+/**
+ * Whether the brace at `at` is the right side of a `where` comparison that
+ * RouterOS reads with the named property's own value parser (#502).
+ *
+ * A `where` clause is expression context, so a brace there is an array value —
+ * except straight after `<name>=`, `<name>!=` or `<name>==`, spaced or not.
+ * On CHR 7.24.5 and 7.23.8, `:parse` rejects `/ip/route/print where
+ * comment={1;2}` with `expected comment value`, and `where disabled={…}` with
+ * `expected yes or no`. It accepts the brace after `in`, `~`, `<`, `>`, `<=`
+ * and `>=`, on the left of `=`, and after `!interface=`, `$x=` and `"a"=`.
+ *
+ * Only a property name the menu KNOWS is read this way: `where foo-bar={…}` is
+ * accepted. Offline has no per-menu property list (decision 3), so every bare
+ * name counts, and an unknown one is a pinned over-strict reading.
+ *
+ * The name may open a group, `where (interface={"x"})` and `or(comment={…})`,
+ * which `group-faults.ts` asks about (#509).
+ */
+export function comparesNamedValue(
+	text: string,
+	at: number,
+	floor: number,
+): boolean {
+	let j = at - 1;
+	while (j > floor && /\s/.test(text[j] as string)) j--;
+	if (text[j] !== "=") return false;
+	while (j > floor && text[j] === "=") j--;
+	if (text[j] === "<" || text[j] === ">") return false;
+	if (text[j] === "!") j--;
+	while (j > floor && /\s/.test(text[j] as string)) j--;
+	const nameEnd = j + 1;
+	while (j > floor && /[A-Za-z0-9._-]/.test(text[j] as string)) j--;
+	const name = text.slice(j + 1, nameEnd);
+	return /^[A-Za-z.]/.test(name) && /[\s(]/.test(text[j] as string);
+}
+
 /**
  * Locate top-level `{...}` values that RouterOS rejects in command arguments.
  *
  * Parentheses and substitutions restore expression context, where a brace
- * literal is legal. Stored-script attributes are also excluded: their brace is
- * a script body, not an array. The caller applies this only to non-root
- * commands; root scripting directives use the `(verb, slot)` table instead.
+ * literal is legal, and so does a `where` clause, apart from the comparisons
+ * {@link comparesNamedValue} names. Stored-script attributes are also
+ * excluded: their brace is a script body, not an array. The caller applies
+ * this only to non-root commands; root scripting directives use the
+ * `(verb, slot)` table instead.
  */
 export function invalidCommandBraceOffsets(
 	text: string,
@@ -1681,6 +1737,7 @@ export function invalidCommandBraceOffsets(
 	let i = Math.max(0, from);
 	let tokenStart: number | null = null;
 	let positionals = 0;
+	let whereAt: number | null = null;
 	while (i < structural.length) {
 		const c = structural[i] as string;
 		if (
@@ -1689,6 +1746,7 @@ export function invalidCommandBraceOffsets(
 		) {
 			if (tokenStart !== null) {
 				const token = structural.slice(tokenStart, i);
+				if (whereAt === null && token === "where") whereAt = i;
 				if (
 					!token.startsWith("?") &&
 					unquotedEquals(token, 0, token.length) === null
@@ -1737,7 +1795,10 @@ export function invalidCommandBraceOffsets(
 				: braceStartsStatements(range.masked, range.start + i, range.start)) ||
 			(directiveVerb !== undefined &&
 				slot !== undefined &&
-				braceSlotAcceptsBrace(directiveVerb, slot))
+				braceSlotAcceptsBrace(directiveVerb, slot)) ||
+			(directiveVerb === undefined &&
+				whereAt !== null &&
+				!comparesNamedValue(structural, i, whereAt))
 		) {
 			i = end ?? structural.length;
 			continue;

package/src/explain/blocks.ts

@@ -13,10 +13,9 @@
  * name (and, for the one head-dependent case, the leading directive) off the
  * statement itself.
  *
- * This module ships only the (single-pass, non-recursive) classification
- * primitives the path resolver needs. The recursive block *tree* / topology
- * surface stays in the lab until it can be promoted with a bounded, index-based
- * traversal of its own.
+ * This module ships the single-pass, non-recursive classification primitives
+ * the path resolver needs. `explain.ts` publishes source ownership from that
+ * resolver's existing bounded traversal; `scopeBlocks` remains a shallow scan.
  *
  * Every string skip here goes through `segment.ts`'s `scanQuotedString` rather
  * than a local quote-to-quote loop, so this module and the segmenter cannot

package/src/explain/brace-slots.ts

@@ -134,6 +134,11 @@ export function braceSlotTakesArray(verb: string, slot: string): boolean {
 	return BRACE_ARRAY_SLOTS.get(verb)?.has(slot) === true;
 }
 
+/** Whether a `{…}` in this root-directive slot is code or script text. */
+export function braceSlotTakesProgram(verb: string, slot: string): boolean {
+	return BRACE_PROGRAM_SLOTS.get(verb)?.has(slot) === true;
+}
+
 /** Whether the device sweep proved this root-directive slot accepts `{...}`. */
 export function braceSlotAcceptsBrace(verb: string, slot: string): boolean {
 	return (

package/src/explain/catalog.ts

@@ -1317,6 +1317,11 @@ export function lookupPath(
 	return PATH_CATALOG.get(`/${segments.join("/").toLowerCase()}`);
 }
 
+/** Segments in the deepest catalog path; no lookup past it can match. */
+const MAX_PATH_DEPTH = Math.max(
+	...Array.from(PATH_CATALOG.keys(), (path) => path.split("/").length - 1),
+);
+
 /**
  * Where a published COMMAND ends inside a path run: the index of the run
  * segment that is the VERB, or `null` when no prefix of `segments` is one.
@@ -1340,12 +1345,14 @@ export function lookupPath(
  * question; what the segment IS is not.
  */
 export function commandVerbIndex(segments: readonly string[]): number | null {
-	for (let depth = 1; depth <= segments.length; depth++)
-		if (
-			PATH_CATALOG.get(`/${segments.slice(0, depth).join("/").toLowerCase()}`)
-				?.kind === "command"
-		)
-			return depth - 1;
+	// Bounded by the deepest row and built incrementally: a run of thousands of
+	// bare words would otherwise re-join every prefix (#496).
+	const limit = Math.min(segments.length, MAX_PATH_DEPTH);
+	let path = "";
+	for (let depth = 0; depth < limit; depth++) {
+		path += `/${(segments[depth] as string).toLowerCase()}`;
+		if (PATH_CATALOG.get(path)?.kind === "command") return depth;
+	}
 	return null;
 }
 

package/src/explain/defects.ts

@@ -99,6 +99,7 @@ export type DefectCode =
 	| "over-depth"
 	| "bad-escape"
 	| "bad-string-escape"
+	| "bad-string-variable"
 	| "bad-sigil"
 	| "invalid-hash"
 	| "invalid-apostrophe"