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

package/commands/explain/README.md

@@ -10,12 +10,11 @@ validation): the cheap, safe knowledge tier in front of the runners
 (`execute` / `api` / `retrieve`).
 
 Status: offline baseline `verified`; live probes over `rest-api` and `native-api`
-`designed`. **`centrs explain '<input>'` runs today**, without a router or CDB.
+`CHR-passed`. **`centrs explain '<input>'` runs without a router or CDB**, and
+`centrs explain <router> '<input>'` adds read-only device evidence.
 [`docs/MATRIX.md`](../../docs/MATRIX.md#offline-analysis) tracks these separately;
 [#90](https://github.com/tikoci/centrs/issues/90) indexes the remaining tasks.
 The spec is ratified on the [phase-0 grounding lab](#phase-0-ratification-185).
-The current finish line is [Offline baseline acceptance](#offline-baseline-acceptance),
-not completion of the live protocol cells.
 Load-bearing rules — envelope, errors, settings precedence, identity,
 validation, protocol selection — live in
 [`docs/CONSTITUTION.md`](../../docs/CONSTITUTION.md).
@@ -373,9 +372,8 @@ native API's `/execute` **with `as-string=""`** returns the parser text —
 including the `(line N column M)` diagnostic on a syntax error — byte-identical
 to what a console transport prints. The opaque `*NN` value seen otherwise is the
 **no-`as-string` job handle**, not a `:parse` limitation; the readout rule is
-"pass `as-string` and interpret `ret`". The existing execute gate already passes
-`as-string` but currently discards `ret`; phase 2 must extract/fix that shared
-readout rather than copy the omission. `/console/inspect`
+"pass `as-string` and interpret `ret`". The execute gate passes
+`as-string` and classifies `ret`; live explain reuses that shared classifier. `/console/inspect`
 (highlight/syntax/completion) works over the native API's `talk` framing too. So
 the line/column diagnostic is available on both live cells — the earlier caveat
 that only a console transport surfaces the parser text is retired.
@@ -401,10 +399,8 @@ router therefore never reinterprets a previously valid offline invocation.
 the offline form with nothing else to analyze. A positional always wins, and
 when fd 0 is redirected anyway the result carries a
 [`usage/stdin-ignored`](../../docs/errors/usage/stdin-ignored.md) warning rather
-than quietly dropping the pipe. `--file -` names stdin explicitly; it is the
-offline fix today, since the live form it also spells
-(`… | centrs explain edge1 --file -`) is parsed and then refused with
-`usage/not-implemented` until phase 2. The narrower rule is
+than quietly dropping the pipe. `--file -` names stdin explicitly in both forms,
+including live `… | centrs explain edge1 --file -`. The narrower rule is
 deliberate and measured: `runCli` is called in-process by tests, so reading fd 0
 on any path a positional invocation reaches consumes the invoking shell's
 stdin — it fed those bytes to the analyzer and broke 21 unrelated tests once,
@@ -652,7 +648,7 @@ and its phase is named below.
 | `structure.statements[].command` | `path` + `verb`, plus **`args` where the argument list was read** (#202c-1); the ordered token list is `statements[].arguments.tokens` |
 | `structure.statements[].transport` | complete for commands: `api-candidate`, `execute`, or fail-closed `unknown`, with an equivalent `centrs` invocation and opt-in `curl` for tested REST mappings (#202c-2). The `basis` names the evidence for the route it chose or refused |
 | `symbols.occurrences[]` | Q13 name/span/class plus semantic `role`, result-local `bindingIds`, sigil spelling, and an abstention note where needed; **plus** (#239 S2) `valueId` on declarations/assignments with a literal RHS in the same statement, and `reachingValueIds` + `reachingUnknown` on references (flow-sensitive, branch → set, loop/non-literal → `unknown`, no RHS evaluation) |
-| `values.occurrences[]` | result-local value id/span plus three separate fact homes: offline `shapeHints`; live `observedType` and `schemaType` remain absent until phase 2. `kind: "element"` rows are array members, carrying `parent` and, for a keyed member, `name` |
+| `values.occurrences[]` | result-local value id/span plus three separate fact homes: offline `shapeHints`; live `observedType` and `schemaType` are added only by a live call ([Live value types](#live-value-types-225)). `kind: "element"` rows are array members, carrying `parent` and, for a keyed member, `name` |
 | `spans` | comment runs and resolved variable classes only; **no value shape or type** |
 | `schema`, `completion` | absent — live evidence, phase 2 |
 
@@ -744,13 +740,10 @@ and its phase is named below.
   rejected by RouterOS at `{` and resolve no reference. In an expression the
   remaining `-dns` is scanned as subtraction plus its right operand; inside a
   string it is literal text.
-- **Evidence is offline-shaped, not the whole contract.** The bullet above says
-  an evidence entry carries `source` (`canonicalizer` vs `live-inspect`) and a
-  RouterOS version stamp; phase 1 emits neither the live source nor the stamp,
-  because no probe ran and there is no device to stamp. `ExplainEvidence` is
-  typed to what offline produces rather than pre-declaring variants nothing can
-  emit, so phase 2 widens the union and adds the stamp — an addition, not a
-  change to what a caller reads today.
+- **Evidence follows its producer.** Offline calls emit only `canonicalizer`
+  entries, with no device version. Live calls add `live-inspect` entries with
+  probe outcomes and available device provenance; existing offline entries
+  retain their meaning. See [Live probe foundation](#live-probe-foundation-491).
 - **Value facts are three axes, never one `type` string (#225).** RouterOS
   types values at parse time while `highlight` classes every value byte `none`,
   so type evidence is not a subset of Q12 spans. Each result-local
@@ -763,7 +756,7 @@ and its phase is named below.
   The stable/testing CHR matrix fixes the offline lexicon: `num`, `ip`,
   `ip-prefix`, `ip6`, `ip6-prefix`, `id`, `time`, `array`, `mac`, `bool`, and
   `str` — `op` is deliberately not a member: a deferred `(> …)` abstains
-  offline and is reported only as a live `observedType` (#288); quoted literals
+  offline and live alike (#288, #225); quoted literals
   hint only `str`, while malformed and out-of-range address-like controls
   abstain even in named attributes. Most vocabulary borrows RouterOS scripting
   type names (with the explicit `macAddr` schema exception below), so a hint
@@ -797,8 +790,9 @@ and its phase is named below.
   1 and identical `:parse` IL — only `:typeof` distinguishes them
   (`test/fixtures/explain/operators.json` → `sweep.runtime`
   `typeof-deferred`/`deferred-array-typeof` and `sweep.opAxis` `defer-*` on
-  7.21.5, 7.23.3, 7.24rc4). Offline abstains on every such form; `op` lives
-  only as a live `observedType` (#288, a bounded #225 decision).
+  7.21.5, 7.23.3, 7.24rc4). Offline abstains on every such form, and so does
+  the live `observedType`, which never sends `:typeof` (#288, #225). `op` has
+  no producer.
   Shape remains non-authoritative: `100000w` is time-shaped but observed as
   `str`. Argument context remains separate: on 7.23.3 and 7.24rc3, both
   `/ip/address address=2.2` and firewall `src-address=2.2` canonicalize it to
@@ -812,8 +806,8 @@ and its phase is named below.
   and does not widen the hint. Thus a hint never validates a value or becomes a
   diagnostic, and never changes `runtimeAcceptance`. Quoting likewise never
   earns a wrong-type diagnostic: commands may cast quoted strings at runtime.
-  Offline emits only `shapeHints`; phase 2 adds the two live facts into their
-  existing homes when its safe IL/schema producers land.
+  Offline emits only `shapeHints`; a live call adds the two live facts into
+  their existing homes ([Live value types](#live-value-types-225)).
 
   **A located array is read member by member (#225 V1).** Each member of a
   `{…}`/`(…)` literal is its own `values.occurrences[]` row with `kind:
@@ -1128,8 +1122,9 @@ navigated, so the context stays as unknown as it already was.
     `empty-group`, `misplaced-separator`, `missing-operand` and
     `invalid-at-sign` (#505, #511, #512, below), and the four token faults
     `glued-token`, `invalid-variable`, `bad-string-variable` and
-    `invalid-name` (#506, #518, below). Seventeen classes the device itself
-    rejects.
+    `invalid-name` (#506, #518, below), and the two unquoted-byte faults
+    `unquoted-reserved-byte` and `unquoted-non-ascii` (#358, #371, below).
+    Nineteen classes the device itself rejects.
   - `warning` — `over-depth`, because it is centrs's own resource bound and says
     nothing about whether the input is legal; `possible-spaced-argument`
     (#350), a spelling RouterOS accepts and marks obsolete; `discarded-close`
@@ -1326,8 +1321,9 @@ query and brace roles. The `$` inside a string is checked by the escape walk
 (`src/explain/quoted-string.ts`), and the stray close by the segmenter
 (`src/explain/segment.ts` → `discardFrom`). Every rule is a `:parse` answer on
 CHR 7.24.5 and 7.23.8, identical on both, and
-`test/fixtures/explain/token-faults.json` pins all 145 rows (80 rejections and
-65 acceptances, with the acceptances' IL). `test/integration/explain-token-faults.test.ts`
+`test/fixtures/explain/token-faults.json` pins these rows and the unquoted-byte
+rows below: 292 in all (184 rejections and 108 acceptances, with the
+acceptances' IL). `test/integration/explain-token-faults.test.ts`
 holds the device to that fixture, and `test/unit/explain-token-faults.test.ts`
 holds offline to it.
 
@@ -1379,11 +1375,59 @@ variable name, so the next `"` does not close the string. Every scanner in
 `explain` closes it there, so both `$` rules and the glued-token rule abstain
 around a string that ends in `$"` (2 of 948 corpus scripts use the form).
 `$$`, `$(…)`, `$[…]` and `${…}` outside a string, where the device's byte is
-not the `$`. A `\` continuation inside a glued token (`"a"\⏎"b"`). The head
-word of a statement (`$v"a"`, `{…}:put 2`). `:local a=b`, which 7.24.5 reads as
+not the `$`. A `\` continuation inside a glued token (`"a"\⏎"b"`). A glued
+head word (`$v"a"`, `{…}:put 2`). `:local a=b`, which 7.24.5 reads as
 a named argument and 7.23.8 as a syntax error. And a name in `/local` or
 `:local name=a_b`.
 
+### Unquoted bytes (#358, #371)
+
+A `?`, a backtick and a non-ASCII byte are never part of a bare word, and
+neither is a second `=` in a menu command's argument. The rules ride the
+token walk (`src/explain/group-faults.ts`). They were grounded with live
+explain (`explainLiveEnvelope`: `:parse` and `highlight`) on CHR 7.24.5 and
+7.23.8, which answered identically. The 147 rows are in
+`test/fixtures/explain/token-faults.json`.
+
+| Code | Device rule | Rejected | Accepted |
+| ---- | ----------- | -------- | -------- |
+| `unquoted-reserved-byte` | `?` and a backtick, at the byte, outside a string or comment. A second `=` in a menu command's argument, at that `=` | `name=a?b`, ``name=a`b``, `name=?b`, `:put a?b`, `[:len a?b]`, `where comment=a?b`, `[find comment=a?b]`, `where (comment=a?b)`, `where comment in {a?b}`, `{a?b}`, `(a?b)`, `/ip/address/print?`, `name=a=b`, `name==b`, `comment=x==`, `url=http://x/a?b=c`, `regexp=^a?b`, `public-key=…=`, `secret=abc==`, `on-event=a=b` | `name="a?b"`, ``name="a`b"``, `name="a=b"`, `where comment=a=b`, `[find comment=a=b]`, `[/ip/address/find comment=a=b]`, `where (comment=a=b)`, `where comment in {"a?b"}`, `{a=b}`, `{"a?"=1}`, `# a?b`, `("a"."?")` |
+| `unquoted-non-ascii` | A non-ASCII byte outside a string or comment, at its first byte; the span is the whole run | `:put café`, `$café`, `name=router-café`, `name=🛰`, `/systemé/identity`, `printé`, `namé=x`, `where comment=café`, `{café}`, `(café)`, `"x"é`, a non-breaking space, `“x”`, `address=…` | `:put "café"`, `:local "café" 1`, `$"café"`, `"a$café"` (`$caf` then `é`), `name="router-🚀"`, `# café`, `do={:put "café"}` |
+
+**Where the device reports, offline reports.** In a menu command's argument
+name the device names the name's first byte (`/ip/address/add addré=1` and
+`a?b=1` at the `a`), so the span is the name. A directive (`:put café=1`) and
+a `$` call (`$f café=1`) report at the byte. A declared name keeps the
+existing `invalid-name` (`:local café`, `:foreach café`). A query, and a
+group or array inside one, keeps `=` as an operator but not these bytes
+(`where (comment=café)` and `in {café}` are rejected at the `é`), and the slash-joined `[/ip/address/find …]` is a query, as
+`[find …]` is. A leading BOM is a positional fact and is not read as part of
+the first word. The informational `non-ascii` fact is still published beside
+the error, so `isPositionalFact("non-ascii")` is unchanged.
+
+**No property parser takes these bytes.** This is the difference from the
+glued-token rule. `regexp=a?b` (layer7 and DNS static), ``regexp=a`b``,
+`public-key=<base64>=`, `secret=abc==`, `password=abc=`,
+`http-header-field=a:b=c` and the script bodies `on-event=a=b` and
+`up-script=a=b` are all rejected at the byte.
+
+**Measured.** Corpus `e12d5d4e58a4`: 8 scripts move to `fail` (7 from `warn`,
+one from `pass`), and 20 already-failing scripts gain a new code. All 28 are
+device rejections on every channel. 8 of their first new errors sit on the
+7.24.5 diagnostic's byte, 20 come after it, and none precedes it. There are no
+false rejects. On the conformance cases, 10 missed rejections move to `fail`
+(the `non-ascii-outside-strings` u10–u12 and u14–u16, z90, z92, g18 and e33), with no new
+false reject.
+
+**Not covered here.** `:put a=b`, `:local x a=b` and `[:len a=b]`: 7.24.5
+reads them as a named argument (`bad parameter a`, at the end), and 7.23.8
+rejects the `=`. A query value that starts with `=` (`where comment==b`,
+`expected comment value`). A bare `source=` value,
+which the device rejects at its first byte whatever it holds (`source=abc`), so
+a byte rule there reports after the device's byte. And `:set` of an undeclared
+name, which the device rejects at the name's first byte (`:set zzz 2`), so
+`:set café` is reported at the `é`, after it.
+
 ### The token stream a rule reads (#316)
 
 `lexArguments` is all-or-nothing by design: its consumer renders a runnable REST
@@ -1599,15 +1643,34 @@ catalog-named command, with a `:` scripting directive, or with an absolute
 command — corpus script `forum/amm0/topic-184067-routeros-lsp-for-better-syntax-checking-command-completion-in-editors-like-vscod/post-0014-snippet-02.rsc` is the directive case,
 `ethernet { :put … }`.
 
-That last rule is bounded by what a STATEMENT can start with, which is what
-keeps `{1;2}` an array literal: an array member opens with a digit or a quote
-and never reaches the identifier branch. It is also deliberately not widened
-into a claim of existence. Menu-scope resolution is schema-dependent —
-`/ip { zzznotamenu { print } }` is a `syntax error` on device — and offline has
-no schema, so a catalog MISS abstains rather than being decided either way.
-That is the catalog's own "a hit is decisive, a miss says nothing" contract, and
-turning such a miss into an acceptance would be the mirror-image defect of the
-one being fixed here.
+Issue #348 only stopped the failure. It still read `address { … }` as a command
+`/ip address` whose operand was the brace, so the body was never segmented.
+That rule was bounded by what a statement can start with, on the theory that
+`{1;2}` there is an array. The device says otherwise (#351, CHR 7.24.5 and
+7.23.8): a brace right after a menu word is a statement block whatever the body
+holds. `/ip { address { 1;2 } }` is `bad command name 1` at the `1`, and
+`/ip { address { a;b } }` runs `a` as `add`. The old reading failed the OUTER
+brace at depth three, and passed `print {1;2}` and `print; zzz` inside the body.
+
+So a relative run inside a menu block now opens a block of its own when the
+menu it names is known: the enclosing block's path, read outward from the
+source, plus the run, named by a shipped structure table
+(`scope-brace.ts` → `menuBlockPath`). The segmenter, the comment mask, the
+argument lexer and the group-fault walk all ask it. The body is then read like
+`/ip/address { … }`: `print {1;2}` there fails at its own `{`, the device's
+byte, and an unresolvable body statement abstains at every depth.
+
+It is deliberately not widened into a claim of existence. Menu-scope
+resolution is schema-dependent — `/ip { zzznotamenu { print } }` is a
+`syntax error` on device — and offline has no schema, so a catalog MISS
+abstains rather than being decided either way. That is the catalog's own "a
+hit is decisive, a miss says nothing" contract. Three spellings keep the older
+reading because the source alone does not name the menu: a block after a
+navigation statement (`/ip⏎address { … }`), an abbreviation (`addr {`) and a
+digit-led menu (`6to4 {`, which the resolver does not read as a path). After a
+navigation, `/ip⏎address { 1;2 }` still fails at the outer brace and
+`/ip⏎address { print {1;2} }` still passes; the device answers
+`bad command name 1` and `expected end of command` at the inner brace.
 
 ### The `=` is optional in ordinary arguments too (#350)
 
@@ -1650,6 +1713,36 @@ device `syntax error` that offline does not report. That is a missed
 rejection for the device preflight to catch, never a false reject. On the
 pinned corpus the widening changed no census.
 
+### First-segment script-body abbreviations warn instead of rejecting (#525)
+
+RouterOS takes any unique prefix of an argument name, including the first
+segment: `down={ :beep }` lowers to `down-script=` on CHR 7.22.1–7.25, as do
+bodies opening with one bare command word (`down={ beep }`) or after a comment
+line. Every word is a prefix of `<word>-script`, so without the command's
+argument list (schema) offline cannot tell `down=` from `comment=`, which the
+device rejects. The contract: on a non-root command, outside `where`, an
+unproven `name={` with a script-like body warns
+`explain/canonicalizer/possible-script-body-abbreviation` (verdict `warn`, the
+offline gate lets it through) instead of failing with `invalid-command-brace` —
+glued or with the brace spaced off the `=` (`down= { :beep }` lowers to
+`down-script=` on CHR 7.25 exactly like the glued spelling, so the spaced
+owner warns under the same gates). The brace reads as a body for every
+reader — a `#` inside is a comment, not `invalid-hash` — while proven slots
+(`down-script=`, `s=`, `on-…`) stay silent and control scopes (`do={…}`) are
+never guesses. A bare word followed by `;`-separated members is array
+members, not commands, so `.proplist={name;comment}` keeps its error alongside
+the other array-content braces (`{1;2}`, `{"x"}`, `{}`), the positional form,
+and `where`. A root directive's slots (`:put x={…}`, glued or spaced) and a `where` named
+comparison (`where gateway={…}`, however wrapped) keep their error too: the
+slot table and the property parser decide there, so the abbreviation guess
+never shields them (#554). The integration twin pins both device directions.
+
+The tradeoff is measured: a verdict sweep of the 948-row pinned corpus
+population against the pre-batch baseline reports zero verdict or diagnostic
+changes, so nothing in the corpus pays for the abstention. The one deliberate
+over-warn — `comment={ :beep }` warns though the device rejects it — has no
+corpus occurrence.
+
 ### `'` is not a RouterOS token (#355)
 
 `'` (U+0027) is not a string delimiter and not a legal bare byte. Only `"` opens
@@ -1986,8 +2079,8 @@ And the grounded complement — asked, and refused:
   `corpus` by `bun run explain:token-census:readme` and gated against it by
   `bun run explain:token-census:readme:check`; the fixture itself is gated
   against a fresh corpus run by `bun run explain:token-census:check`. Of
-  1,426,731 analyzed bytes, 1,022,782 are classified (71.69%), the remaining
-  403,949 are `unclassified`. The census emits 241,279 tokens (avg 254.5 per
+  1,426,731 analyzed bytes, 1,022,786 are classified (71.69%), the remaining
+  403,945 are `unclassified`. The census emits 241,282 tokens (avg 254.5 per
   script). Every byte belongs to exactly one token — sorted by `start`, no
   gaps, no overlaps, `join(slice) === input` — and the `class` field is the
   vocabulary #264 B5 settled. Each B2 fill should move the classified
@@ -2468,22 +2561,317 @@ last byte. The `$` sigil and the `[` / `]` of a substitution stay `string` on
 the same ground — `structure.subcommands` already publishes the resolution, and
 its `innerSpan` locates the brackets around it.
 
-### Designed, not implemented (the CLI surface, #202b)
-
-`src/cli/explain.ts` ships the offline command; implemented flags are generated
-into [`docs/CLI.md`](../../docs/CLI.md) and are not restated here. What the
-[Surface](#surface-option-a--decided) table above describes and the command does
-**not** yet accept:
-
-| Flag / form | Phase | Why it is not accepted yet |
-| ----------- | ----- | -------------------------- |
-| `explain <router> '<input>'` | 2 | The grammar is parsed and **refused** with `usage/not-implemented`, naming the router it did not contact. Running the offline analysis under an invocation that asked for probes would report `mode: "offline"` about a request for more. |
-| `--cursor <byte>` | 2 | It positions `--complete`, which enumerates nothing offline. A cursor with no candidate surface to position is a flag with no effect. |
-| `--full` | 3 | It lifts smart-sizing limits, and the offline result is never truncated (`input.truncated` is always `false`). Same rule: no accepted flag is a no-op. |
-
-`--complete` and `--schema` **are** accepted, because they have an offline
-behavior the spec names: they enumerate nothing and emit the live-target tip.
-That is the difference — an accepted flag must do something observable.
+### Live probe foundation (#491)
+
+`centrs explain <router> '<input>'` (or `--quickchr <name>` / `--host <host>`)
+adds read-only device evidence over REST or native API. Library callers use
+`explainLiveEnvelope({ input, targetInput, via, ... }, options)` from the root
+package; the browser-safe `@tikoci/centrs/explain` entry remains offline.
+Connection/authentication settings use the existing resolver and provider
+precedence. A pinned unsupported transport is refused. No fan-out or protocol
+fallback is performed. `AbortSignal` cancels library probes.
+An explicitly supplied connection flag such as `--via`, `--password` or
+`--timeout` without `<router>`, `--host` or `--quickchr` is a usage error before
+input is read. Connection defaults from environment and config remain inert in
+offline mode.
+Text output summarizes live observations; `--json` retains full parse and
+per-byte highlight evidence.
+
+`data.canonical`, structure, symbols, values and optional tokens retain the
+offline result. Live observations are additional facts:
+
+- `data.live.environment` records the observed version, architecture and board.
+- `data.live.parse` carries the printed parse result, rejection classification
+  and authoritative line/byte-column when reported. Only an escaped
+  `:put [:parse "…"]` wrapper runs; the analyzed input, substitutions and
+  deferred bodies are never executed.
+- `data.live.highlight` retains raw device classes. Additional `data.spans`
+  cite its evidence and use centrs classes: `dir`, `cmd`, `arg`, `escaped`,
+  comments and variable classes; device state, syntax-meta, error/obsolete and
+  unknown classes map to `unclassified`. Error/obsolete markers produce separate
+  diagnostics. Offline and live spans can overlap; distinguish them by `ev`.
+- `data.live.arguments[]` contains `path`, `names`, `statementIds` and `ev` for
+  command-level `request=child`. Repeated paths share a probe. Names confirm what
+  the device exposes; they do not rewrite offline arguments, transport eligibility
+  or lexical bindings. The highlight obsolete marker distinguishes `name x`
+  from the two flags `detail without-paging` (example 48).
+
+Every live evidence entry identifies its probe, observation time, known version
+and acquisition outcome. Input probes include SHA-256 and normalization;
+`coverage` identifies the submitted byte range for a usable response, not proof
+that every byte is syntactically valid. Parse uses original UTF-8 input;
+highlight uses the existing one-SUB-per-non-ASCII-byte normalization. Its facts
+therefore describe that explicit variant; both spaces align with `positionMap`.
+Parse can stop at its first error; highlight `none` remains unclassified.
+
+Probe outcomes distinguish `ok`, `empty`, `unsupported`, `skipped`, `timeout`,
+`auth-error`, `transport-error`, `interrupted` and `invalid-response`. A parse
+rejection is an acquired response (`ok`) plus a diagnostic, not a transport
+failure. A failed/skipped probe adds a warning diagnostic; acquired offline and
+live facts remain available. `ok:true` means analysis produced a result, never
+that all probes succeeded. Resolver/usage failures and transport/authentication/interruption failures before
+any input probe yields a result remain `ok:false`.
+`meta.operation.mode` is `live`; no execution-validation verdict is invented:
+`meta.validation` is `{ enabled: false }`, offline and live, because explain
+is not a gate (#535). `runtimeAcceptance` always remains `not-proven`.
+
+Work is bounded by the resolved per-request timeout, 32 distinct command paths,
+32,767 bytes for highlight and 65,536 bytes for parse. Larger probes are skipped
+with their reason; no silent prefix is submitted and `input.truncated` stays
+false. A transport/authentication failure stops later requests. Scripting-path
+discovery is conservatively skipped before 7.21.4 or on unknown versions. No
+command-level completion, user-expression evaluation or related
+configuration-table collection is part of this slice. `--schema` and
+`--complete` add the probes in the next section, and the value-type probes
+after it run on every live call.
+
+Committed controls are
+[`live-probes.stable.json`](../../test/fixtures/explain/live-probes.stable.json)
+(7.24.5) and
+[`live-probes.long-term.json`](../../test/fixtures/explain/live-probes.long-term.json)
+(7.23.8), both CHR reporting `x86_64`, with package manifests, input hashes,
+observation times, raw parse/highlight output and projected child names. Each
+fixture records its capture command. `test/unit/explain-live.test.ts` replays
+the parse classifier and source-aligned highlighter against these controls;
+`test/integration/explain-live.test.ts` repeats the probes on a real CHR and
+checks that the analyzed identity-setting command did not run.
+
+### Live describe and completion (#492)
+
+`--schema` and `--complete` work on the statement at the cursor. The cursor
+defaults to the end of the input. `--cursor <byte>` is a UTF-8 byte offset,
+which is also the analyzed and device byte offset. Library callers may pass
+`cursor: { line, character }` (0-based, UTF-16) instead. A cursor inside a
+multi-byte character moves back to its first byte. A cursor outside the input
+is [`usage/invalid-cursor`](../../docs/errors/usage/invalid-cursor.md), raised
+before connecting. `--cursor` or `--full` without a facet is
+`usage/conflicting-flags`. Offline, both facets still return the live-target
+tip and enumerate nothing.
+
+**Probe shapes.** Grounded on CHR 7.12.2, 7.20.8, 7.23.8 and 7.24.5 over REST
+and native API:
+
+- `child` names what exists at a path and resolves unique abbreviations
+  (`ip,addr` answers as `address`). It is safe on every build tried.
+- `syntax` is sent only for an **argument** path (`ip,address,set,address`,
+  `put,message`). That shape answers in about 25 ms on every build, scripting
+  keywords included.
+- `completion` is sent only with `input=`, the text before the cursor. It is
+  safe at every position tried, including scripting keywords and `do={`
+  bodies on 7.20.8.
+- Never sent: `syntax` or `completion` with `path=` set to a **command**
+  (`ip,address,set`). On 7.12.2 and 7.20.8 REST stops answering, and the
+  requests queued behind it stall, for about 30 s. Native API closes the
+  connection. 7.23.8 and later answer normally, but the rule is
+  version-independent (`commands/api/AGENTS.md`). restraml's crawlers never
+  meet this, because they send `syntax` to `arg` nodes only.
+
+Every probe is an `evidence[]` entry with `facet: "schema" | "complete"`, its
+path, version and outcome. Facts cite it by `ev`. A facet probe that answers
+`empty` is a result, so it adds no warning diagnostic. Other failed outcomes
+warn as in the foundation, and a transport or authentication failure stops
+later probes.
+
+**`data.schema`** describes one path: the resolved statement, or an absolute
+slash path as typed (`/ip/addr`). The `child` self row decides `node`:
+
+- `menu`: `verbs[]` and `menus[]`. Each child is expanded by one more `child`
+  probe into `arguments` (verb) or `verbs`/`menus` (submenu) counts.
+- `command`: `arguments[]`, each with its argument-level `syntax` rows. A
+  flag's blank row is dropped. For `print`, `proplist` holds the output-field
+  names from `print proplist=` (`source: "print-proplist"`). A singleton
+  settings menu offers none there, so `get value-name=` answers instead
+  (`source: "get-value-name"`; `/ip/dns`, `/system/identity`). These are names
+  a print can show, **not print rows**.
+- `argument`: its `syntax` rows.
+- `unknown`: the device reports nothing there, or the statement at the cursor
+  is neither resolved nor an absolute path (`reason`).
+
+Syntax rows are kept verbatim (`symbol`, RouterOS `symbol-type` as `kind`,
+`text`, `nested` as `depth`). They are declared help, such as
+`A.B.C.D (IP address)` or `input | forward | output` beside `string value`.
+They are not the `schemaType` value fact, which normalizes the same rows per
+value ([Live value types](#live-value-types-225)).
+
+**Smart sizing.** By default each list shows up to 64 names, and expansion
+runs only when the listed children fit in 16 probes (a menu's children, or a
+command's arguments for their `syntax`). Otherwise names are listed without
+expansion. `counts` always holds the full sizes, `truncated: true`, `next[]`
+names up to three narrower inputs, and the envelope carries
+`tip/explain-schema-truncated`. On CHR 7.24.5, `/ip` (2 verbs, 29 menus) and
+`/ip/address/print` (21 arguments) truncate; `/ip/address` (12 verbs) and
+`/ip/firewall/filter` (16) do not. `--full` raises the limits to 1024 names and
+128 probes. That is the safety ceiling, not unlimited.
+
+**`data.completion`** reports `cursor`, `at` (original line/character),
+`replace` (the bytes a candidate replaces, ending at the cursor), `prefix`,
+`context`, `candidates[]`, `count` and `truncated`. Candidates are capped like
+names. They are the device's own: one input completion of the text before the
+cursor, keeping shown, non-syntax rows. The row `offset` sets `replace`. The
+navigation punctuation (`/`, `:`, `..`) offered everywhere is left out. So a
+relative path, a block, a `where` clause or an unclosed `[` completes exactly
+as on the console: `/ip { :put 1; address add comm` → `comment`, and
+`/ip address⏎` → that menu's verbs. Where the device offers nothing, neither
+does explain: `do={ add comm` runs at root, so `add` is unknown there.
+
+The `context` comes from the device highlight of the same text. When the
+cursor is not at the end, that is one extra highlight probe whose `coverage`
+says so.
+
+- `path`: in a `dir`/`cmd` word, after a menu, or at the start of a line.
+  Candidates are `menu` or `verb` by row style. A word the device cannot
+  resolve there is `obj-inactive`, and the token before it gives its role:
+  `/ip/address re` → `remove`, `reset`, and `:lo` → `local`, `lock`, `log`.
+- `argument-name`: in an `arg` word, or after a command, flag or value.
+  `match: "exact"` marks a complete name. `takesValue` is whether the same
+  answer offers `=` at the cursor: `comment` does, and the flag `detail` does
+  not.
+- `variable`: a `where` clause, whose property names RouterOS scopes as
+  variables (`where comm` → `comment`).
+- `value`: after `name=`. Candidates may include configuration state, such as
+  interface names. They are never a closed set:
+  `chain=` offers `forward`, `input` and `output`, but custom chains are legal.
+  For a command argument, `syntax` carries its declared type text, so a
+  free-form `comment=` returns no candidates and `string value`. A `where`
+  value (`disabled=` → `no`, `yes`) has no argument path, so no `syntax` is
+  read.
+- `unsupported` with a `reason`: strings, the obsolete spaced `name value`
+  spelling, and other tokens the device does not class as a path, name or
+  value.
+
+Every candidate is an observation of the completion probe its `ev` cites.
+The declared side is `data.schema`: `child` names and argument `syntax`. So
+completion carries no second provenance label, and nothing in it is a closed
+set. `path` names the command at the
+cursor when it is known. It comes from the offline statement or `[…]`
+substitution when that resolved, otherwise from the device's `dir`/`cmd` runs.
+The command is needed only for a value's `syntax`. When it is not visible (a
+relative path after `;`), the candidates are unaffected and `syntax` is
+omitted.
+
+The verdict still judges the input as written, and the two probes agree on
+it. `/ip/address add comm` is rejected by `:parse` (`expected end of command`
+at byte 16), and the highlight marks the same byte `error`. So the result
+fails even while its candidates are published. An assist loop that only wants
+candidates passes `--fail-on never`.
+
+Committed controls are
+[`live-facets.stable.json`](../../test/fixtures/explain/live-facets.stable.json)
+(7.24.5) and
+[`live-facets.long-term.json`](../../test/fixtures/explain/live-facets.long-term.json)
+(7.23.8). They hold every recorded call and its raw answer, plus the projected
+result. `test/unit/explain-live-facets.test.ts` replays them.
+`test/integration/explain-live-facets.test.ts` asserts the examples on both
+transports and regenerates the captures when `CENTRS_EXPLAIN_FACETS_CAPTURE`
+names an output file.
+
+Not covered here: MCP (#223), related print rows and topic checks (#493),
+and per-target caching of describe results (open 3).
+
+### Live value types (#225)
+
+Every live call fills the two live homes on `data.values.occurrences[].facts`
+that offline leaves empty. Neither changes the verdict or
+`runtimeAcceptance`, and neither becomes a diagnostic. Both probes are
+`evidence[]` entries with `facet: "types"` and `basis: "derived"`; an `empty`
+answer is a result, not a warning. They run after `--schema`/`--complete`.
+
+**`observedType: { value, rendered, ev }`** is the type the device's parser
+visibly converted a bare literal to. `:parse` prints a string unquoted, so
+`:local a 123` and `:local b "123"` both render `value=123`. A rendering is
+therefore evidence only when it CHANGED the literal:
+
+| Literal | Device rendering | `observedType` |
+| ------- | ---------------- | -------------- |
+| `2.2`, `2.2/8` | `2.0.0.2`, `2.0.0.2/8` | `ip`, `ip-prefix` |
+| `1:0:0::1` | `1::1` | `ip6` |
+| `0x10`, `0123`, `99999999999999999999` | `16`, `123`, `9223372036854775807` | `num` |
+| `yes`, `no` | `true`, `false` | `bool` |
+| `200ms`, `1d`, `1:2`, `10000w` | `00:00:00.200`, `1d00:00:00`, `01:02:00`, `10000w00:00:00` | `time` |
+| `123`, `1.1.1.1`, `true`, `00:00:02`, `"2.2"` | unchanged | absent |
+| `100000w`, `abc`, `1e5`, `300.1.1.1` | unchanged | absent |
+| member `{abc}`, `{-1}` | `$abc`, `(- 1)` | absent |
+
+The literal is not looked up in the IL of the analyzed input, where a quoted
+`"x;y=1"` prints exactly like two arguments. Each bare literal is re-parsed
+alone: `:local vN <lit>` for a scripting operand, `:local vN {<lit>}` for an
+array member, `;`-joined into one escaped `:put [:parse "…"]` per context.
+`:put <lit>` converts exactly as `:local` does. Only literals of the bytes
+`A-Z a-z 0-9 . _ : / -` are sent, so no literal can leave its slot, and a
+quoted value never qualifies. One hard-error member (`{*1}`) rejects a whole
+batch, so the two contexts are separate probes and a rejected batch is
+`invalid-response` with the device's message; its literals abstain. A batch is
+at most 256 literals, otherwise `skipped`.
+
+A scripting directive's named argument converts exactly as an operand
+(`:for i from=0x10` → `from=16`, `:put message=yes` → `message=true`), so it
+joins the operand batch. A directive's NAME slot is a variable and never
+converts: `:local yes 2` renders `name=$yes`, `:for yes from=1` renders
+`counter=$yes` and `:local name=no` renders `name=$no`. So a value the symbol
+view claims as a name, or a directive's `name=`/`counter=` argument, is never
+probed.
+
+Menu-command arguments are never observed. Their own parser converts them
+and prints a per-argument encoding (`src-address=!1.1.1.1` →
+`true;1.1.1.1`, `address=2.2` → `2.0.0.2;`), and a quoted value converts only
+at run time (`address="2.2"` stays `2.2`). That slot is `schemaType`'s. `op`
+has no producer: `(>[:return 1])` and `(>{"a"=1})` parse identically, and only
+`:typeof` separates them.
+
+**`schemaType: { values, list?, declared, ev }`** is the argument's declared
+type. For each `name=value` of a resolved menu command, the name is resolved
+against that command's live `child` names, exactly or as a unique prefix
+(`dist=` → `distance`). One `syntax` probe per distinct argument path
+(`ip,route,add,distance`) reads the declaration; at most 32 per call, later
+ones `skipped`. An ambiguous or unknown name sends no probe. `syntax` is never
+sent to a command path (see [Live describe and completion](#live-describe-and-completion-492)).
+
+The rows are a small grammar (`[!]Range`, `Address[%Interface][@VRF]`), so
+`values` lists the LEAF types the declaration mentions, not alternatives of
+one value. They use the shape-hint names so the two axes compare directly,
+plus three schema-only terms:
+
+| Device leaf | Term |
+| ----------- | ---- |
+| `(integer number)`, `(decimal number)`, `integer value`, `0..65535` | `num` |
+| `(time interval)`, `time interval` | `time` |
+| `(IP address)`, `IPv4 address`, `A.B.C.D` | `ip` |
+| `IPv6 address` | `ip6` |
+| `(IP prefix)`, `(IPv6 prefix)` | `ip-prefix`, `ip6-prefix` |
+| `(IP address range)` | `ip-range` |
+| `(MAC address)` | `mac` |
+| `string value…`, `hexadecimal string value…`, `script`, `filename` | `str` |
+| a listed word set (`input \| forward \| output`, `ether1 \| lo \| ...`) | `enum` |
+
+`enum` is never a closed set: the device lists the current configuration
+names (`ether1 | lo`) exactly like keywords, and ends either kind with `...`
+when the list is long (`ftp | h323 | … | ...`). `list: true` is present when
+the declaration spells a repetition (`[,Type*]`, `(max 15 times)`); its
+absence is not a claim — `servers` (`Address[@VRF]`) splits on a comma
+without saying so. A keyword's help row (`tcp` → `transmission control
+protocol`) is not a leaf, and a blank placeholder beside a real leaf is
+skipped. The fact is ABSENT when the declaration is blank (every flag and
+boolean: `disabled`, `copy-from`) or when any leaf is `see documentation`
+(`/ipv6/address add address`). `declared` is the device's top-level text,
+verbatim (`Address[@VRF]`, `Num`).
+
+The vocabulary also names `bool` and `name` for a second schema source: the
+CLI Reference's `Type` cells (`bool`, `iface_enum`, `ipAddr`, `macAddr`,
+`ubit (…)`), which declare the booleans and object references inspect leaves
+blank or prints as words. A CLI Reference producer would fill the same fact,
+told apart by its `ev`; delivering those tables is decision 3 (#501).
+
+Grounded on CHR 7.24.5 and 7.23.8 over REST and native API, identical on both:
+a 40-command crawl (863 arguments) set the leaf table (571 project, 282 are
+blank, 7 cite `see documentation` and 3 list no names), and the conversion
+matrix is recorded raw in
+[`live-types.stable.json`](../../test/fixtures/explain/live-types.stable.json)
+and [`live-types.long-term.json`](../../test/fixtures/explain/live-types.long-term.json).
+`test/unit/explain-live-types.test.ts` replays them and pins the matrix
+reading; `test/integration/explain-live-types.test.ts` asserts examples 52–53
+on both transports and that every executed script is a `:parse` wrapper and
+every `syntax` probe names a discovered argument. It regenerates the captures
+when `CENTRS_EXPLAIN_TYPES_CAPTURE` names an output file.
 
 ## MCP and library surfaces
 
@@ -2988,9 +3376,10 @@ test framework is part of this baseline.
 
 ### Current and following capabilities
 
-- **Current — live probes (#236, phase 2):** highlight + `:parse` and
-  completion/child/syntax over rest-api/native-api. B4's projection/agreement
-  informs this work; each live cell requires its own CHR-passing examples.
+- **Done — live probes (#236, phase 2):** highlight + `:parse` (#491),
+  completion/child/syntax (#492) and live value types (#225) over
+  rest-api/native-api, `CHR-passed` on stable and long-term.
+  `runtimeAcceptance` stays `not-proven`.
 - **MCP alignment (#223):** the deliberate flat-to-rich response migration,
   coordinated with rosetta. Independent of the offline token vocabulary.
 - **Facet polish (phase 3):** live sizing, `--full`, completion/schema ergonomics.
@@ -3061,8 +3450,10 @@ round):
 
 Still open (implementation opens — none block ratification):
 
-1. Final flag names (`--full`, `--curl`, facet names) and the smart-sizing
-   thresholds (what counts as "cheap", what triggers truncation).
+1. ~~Final flag names and smart-sizing thresholds.~~ Decided by #492:
+   `--schema`, `--complete`, `--cursor <byte>` and `--full`; 64 names and 16
+   expansion probes by default, and 1024 / 128 with `--full`
+   ([Live describe and completion](#live-describe-and-completion-492)).
 2. The mapping table from RouterOS highlight classes to **colors**, and how
    unknown/new upstream classes degrade. Phase 0 pinned the raw inputs (Q13's
    per-occurrence highlight-class corpus; the observed 19 classes on 7.23.2 plus