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

package/CHANGELOG.md

@@ -17,6 +17,29 @@ part of this section.
 
 ### Added
 
+- **Live `explain` over rest-api + native-api is `CHR-passed`** (#236).
+  Examples 7–16, 19, 24, 48 and 52–53 pass on both transports on stable
+  7.24.5 and long-term 7.23.8. `runtimeAcceptance` stays `not-proven`.
+- `explain <router> '<input>'` and `explainLiveEnvelope()` add read-only parse,
+  highlight and command-argument evidence over REST/native API. Probe outcomes,
+  byte coverage and provenance remain explicit; analyzed input never executes (#491).
+- Live `explain` fills the two live value facts (#225). `observedType` names a
+  type only where the device visibly converts a bare scripting literal
+  (`2.2` → `2.0.0.2` is `ip`, `0x10` → `16` is `num`), read from an escaped
+  `:parse` of the literal alone; an unchanged rendering abstains, and no
+  `:typeof` is sent. `schemaType` normalizes the argument's live `syntax`
+  declaration into leaf types (`gateway` → `ip`, `ip6`, `enum`), with the
+  device's own term in `declared`. Menu arguments are never observed, and
+  `op` has no producer.
+- Live `explain --schema` describes the path at the cursor: a menu's verbs and
+  submenus with counts, a command's arguments with their declared syntax, and
+  `print`'s proplist. `--complete [--cursor <byte>]` returns menu, verb,
+  argument-name, `where` variable or value candidates. They are the device's
+  own input completion at the cursor, cited by `ev`; declared names and
+  syntax stay in `--schema`. `--full` lifts the sizing limits up to a safety
+  ceiling.
+  Only probe shapes that answer on RouterOS 7.12.2 and 7.20.8 are sent (#492).
+
 - `centrs --version` / `-V` prints the package version alone; `--json` (or
   `--format json|yaml`) returns an envelope with `data.version` (#463).
 - `execute --cmr` warns `cmr/caller-policy-not-enforced` when a write runs
@@ -72,6 +95,34 @@ part of this section.
 
 ### Changed
 
+- **Breaking:** permission and edge-auth failures get their own error codes
+  (#541). Three codes change for `--json` and library readers:
+  - A REST policy refusal (HTTP 500 `not enough permissions (9)` or `std
+    failure: not allowed (9)`): `transport/connection-closed` →
+    `routeros/permission-denied`. It is a deterministic router answer, so it
+    is never retried and no longer carries
+    `transport/write-outcome-unknown`.
+  - A native-API `not enough permissions (9)` trap: `routeros/api-trap` →
+    `routeros/permission-denied`. Retrieve's path probe and live explain's
+    child probe surface it instead of reading "path doesn't exist".
+  - A 401/403 from a layer in front of RouterOS (auth proxy, tunnel edge,
+    WAF): `transport/auth-failed` → `transport/edge-auth-failed`, with the
+    challenge scheme, server, content type and `cf-ray` presence as context
+    (no secrets). RouterOS's own 401 — JSON `{"error":401,...}`, measured on
+    CHR 7.12.1, 7.16.2, 7.23.8, 7.25, 7.26beta1 and 7.26beta3 — stays
+    `transport/auth-failed`.
+- **`meta.validation` success shapes (#535).** This is a breaking change for
+  `--json` readers of the flat fields. `syntax` and `semantic` are now present
+  only when a gate stage gave that verdict; absent means no stage was asked.
+  - `api` structured requests (no `:parse`) drop `syntax: false`.
+  - Script input drops `semantic: "not-applicable"`; the value is gone from
+    the type.
+  - `--validate=false` drops both fields on `execute` and `api`.
+  - `retrieve`, `transfer` and `api` structured successes now report
+    `stages[]`. `transfer list` runs no existence probe, so it reports
+    `{ enabled: false }` instead of claiming one.
+  - `explain` reports `meta.validation: { enabled: false }` with no `result`
+    in all three cases (offline, live, error); it is not a gate.
 - Text stdout is data (#470). In text mode, single-target `execute`, `api`,
   `retrieve` and `transfer` write only the result to stdout. Everything else
   goes to **stderr** on success and on failure: the `--verbose` header, one
@@ -150,6 +201,13 @@ part of this section.
 
 ### Fixed
 
+- `retrieve --sample`, `--follow` and `--wait` no longer report a validation
+  verdict the gate never gave (#537). A cancellation before the gate ran now
+  reports the device stage `not reached` (`interrupted` for `--sample` and
+  `--follow`, `wait/interrupted` for `--wait`) instead of
+  `{enabled: true, result: "skipped"}`. A `--wait` cancelled after retried,
+  unanswered attempts no longer reports `result: "failed"`. With validation
+  off, all three report `{enabled: false, source: "disabled"}`.
 - Abbreviated output-file arguments (`fi=`, `file-n=`), and the spaced
   `file-name value` form under print/export/serialize, require write
   confirmation in `execute`, including inside scripts, and are refused for
@@ -181,6 +239,50 @@ part of this section.
   a native API login. A write that failed after it was sent, in single-target
   or fan-out mode, carries the new warning `transport/write-outcome-unknown`,
   because it may have run. Reads keep the retry.
+- A bare known-menu path (`/system/identity`) reads as a read in `execute`,
+  not `usage/confirmation-required` (#543). It still answers nothing, so the
+  envelope steers to `/print` / `retrieve` with `tip/execute-bare-menu-path`.
+  Unknown paths, known-mutator verbs, and any attribute or query stay gated.
+- `retrieve /system/routerboard` on a router without the menu (CHR) names the
+  workaround: the `validation/unknown-path` remediation points at
+  `/system/license --attributes system-id` instead of the generic text (#545).
+- `execute` warns when a multi-statement write is refused for permission after
+  earlier statements may have run (#549). Such a refusal carries
+  `transport/write-outcome-unknown` alongside `routeros/permission-denied`,
+  counting statements inside executed `:if`/`:for`/`:foreach`/`:while`/`:do`/`:retry`/`:onerror` scopes and
+  command substitutions (`[…]`) as well as top-level ones; a `/menu { … }`
+  prefix is navigation, not a statement. Single refused statements, including
+  `remove [find …]` and one wrapped in a menu block, stay silent. The refusal itself
+  now surfaces as the error instead of `ok:true`: `/execute` answers HTTP 200
+  with `not enough permissions (9) (…; line N)` as the last `ret` line after
+  earlier statements' output (CHR 7.25, both transports).
+- The offline gate no longer hard-rejects first-segment script-body
+  abbreviations it cannot prove (#525). `down={ :beep }`, accepted on device
+  as `down-script=`, warns `explain/canonicalizer/possible-script-body-abbreviation` and
+  reaches device validation instead of failing with `invalid-command-brace`. Bodies
+  opening with one bare command word or after a comment line warn too, and
+  the brace reads as a body for every reader, and whitespace after the `=`
+  (`down= { :beep }`) warns like the glued spelling. A bare word followed by
+  `;`-separated members keeps its error, as do the other array-content
+  braces (`comment= {1;2}` included), the space-for-`=` spelling
+  (`comment { :beep }`), positional braces, root directive slots
+  (`:put x={…}`), and `where`; `comment={ :beep }` deliberately warns though
+  the device rejects it.
+- Native-API traps classify authentication by sentence, never trap text
+  (#540). Only a trap on `/login` is `transport/auth-failed`; a later command
+  rejected with login-like text (`/user/add name=-2` answering `invalid user
+  name`) is `routeros/command-failed`, agreeing with REST.
+- `explain` symbols declare the value of named `name=`/`counter=` spellings in
+  any argument order (#533). `:local name=no` declares `no`, and
+  `:for from=1 counter=i to=2` binds `i`, so later `$` references link;
+  previously the argument name was declared and a reordered `counter=` left
+  `$i` unbound.
+- mac-telnet with an explicit directed-broadcast `--host` (`192.168.74.255`)
+  sends the owning interface's real MAC (#546, #547). On Linux, `connect()` to
+  a broadcast reports `0.0.0.0`, so the session fell back to a synthetic
+  source MAC, which hardware ignores: a 30 s timeout on an RB1100Dx4 running
+  7.26beta3. On that unit a real MAC gets a reply in ~0.35 s and a synthetic
+  one none. CHR answers both, so the CHR suite never saw it.
 
 ### Maintenance
 
@@ -200,6 +302,10 @@ part of this section.
   (Security tab), and locally with `bun run lint:actions` (#266). Its first
   run found two `${{ … }}` expansions inside shell scripts, in `lab.yaml` and
   `qa.yaml`; both now go through `env:`.
+- The unit tier no longer reads the developer's `~/.config/tikoci` state
+  (settings, CDB) (#550, #557). A `bunfig.toml` preload sandboxes `HOME` and
+  `XDG_CONFIG_HOME`, so a real and a fake home give the same result. Ambient
+  `CENTRS_*` variables are still read.
 
 ## 0.1.8 — 2026-10-12
 

package/GLOSSARY.txt

@@ -821,3 +821,17 @@ apptraffic # two paths new in 7.26beta1 with different published gates: the `/to
 rle # the corpus's `highlight-rle-v1` response encoding: each highlight stream stored as run-length `[class, count]` pairs, decoded by `decodeHighlightRuns` in scripts/corpus-db.ts (#498)
 removenumbers # the IL head `/ip/firewall/address-list/removenumbers=…` that `remove [find …]` renders as, quoted verbatim in the bracket-`=` corroboration test (#498)
 vscod # the last segment of a corpus path the forum importer truncated at its slug limit (`…-editors-like-vscod/post-0014-snippet-02.rsc`); cited as the path, so the spelling must match the corpus row (#498)
+
+# #358/#371 unquoted-byte controls. Deliberate NON-words: each puts a non-ASCII
+# byte where RouterOS reads only ASCII, so the spelling is the probe.
+systemé # `/systemé/identity print` — a non-ASCII byte in a path, `expected command name` at the `é` on CHR 7.24.5/7.23.8 (#371)
+printé # `/system/identity printé` — a non-ASCII byte in a verb, rejected at the `é` (#371)
+namé # `/system/identity/set namé=x` — a non-ASCII byte in a menu command's argument name, rejected at the name's first byte (#371)
+addré # `/ip/address/add addré=1` — as `namé`: the device reports the argument name's first byte, not the `é` (#371)
+caf # the ASCII prefix the device reads of `café` before the `é`: `:put "a$café"` is `$caf` then `é` (#371)
+
+# #225 live value types: CLI Reference `Type` cell spellings the schema vocabulary maps.
+iface # the CLI Reference type `iface_enum`: an argument that names an interface, which `schemaType` calls `name` (#225)
+ubit # the CLI Reference type `ubit (…)`: a set of listed bits, e.g. `ubit (pap, chap, mschap1, mschap2)`, a list of `enum` (#225)
+forcounter # the IL head `/forcounter=$i;…` that `:for i …` renders as; quoted verbatim in the #225 directive-argument probe test (#225)
+foreachcounter # the IL head `/foreachcounter=$i;…` that `:foreach i …` renders as, in any `counter=` order; quoted verbatim in the #533 reorder test (#533)

package/README.md

@@ -1,8 +1,8 @@
 # centrs
 
 `centrs` is the tikoci RouterOS interaction hub: a Bun/TypeScript library and
-CLI (with MCP, TUI, and HTTP proxy frontends planned) for talking to MikroTik
-RouterOS devices through a regularized, validated interface.
+CLI (with an MCP server; TUI and HTTP proxy frontends planned) for talking to
+MikroTik RouterOS devices through a regularized, validated interface.
 
 Preview builds are published on npm. To try the current offline analyzer without
 installing centrs or connecting to a router:

package/commands/api/AGENTS.md

@@ -184,7 +184,7 @@ green on CHR 7.23.1.
   validity (`request=child` ⇒ `validation/unknown-attribute`) fire
   identically over rest-api and native-api, **before** any write — no `:put
   [:parse]` involved (api input is a path, not a CLI string). A `/execute` script
-  is a CLI string ⇒ `meta.validation.semantic = "not-applicable"`.
+  is a CLI string ⇒ no `meta.validation.semantic` field (#535).
 
 ## CONFIRMED ON CHR (RouterOS 7.12.2 compatibility — GH#343, 2026-09-14)
 
@@ -197,6 +197,23 @@ green on CHR 7.23.1.
   validation therefore uses command-level `request=child` only. This does not
   prohibit argument-level completion probes such as `print,proplist`, which are
   a separate shape and returned immediately on the same 7.12.2 controls.
+- **Command-level `request=syntax` is unsafe too, on 7.12.2 and 7.20.8** (#492,
+  2026-10-19, reproduced on a fresh boot of each).
+  - REST: `syntax` with `path=` set to a command (`ip,address,set`,
+    `system,identity,set`, `ip,route,add`, `interface,print`) got no answer
+    within 12 s, 5 of 5 times. The `child` controls queued behind it timed out
+    until the handler recovered about 30 s later.
+  - Native API closed the connection.
+  - The same syntax requests at a menu (`ip,address`) or an argument
+    (`ip,address,set,address`, `put,message`, `do,command`) answered in about
+    25 ms. 7.23.8 and 7.24.5 answer every shape.
+  - restraml's crawlers send `syntax` to `arg` nodes only, so `inspect.json`
+    never exercised the hanging shape.
+  - Input-based `completion` (`input="/ip/address add comm"`) answered at every
+    position tried on both builds, including scripting keywords and `do={`
+    bodies on 7.20.8.
+  - Explain's `--schema`/`--complete` therefore send `syntax` for argument
+    paths and `completion` with `input=` only.
 
 ## CONFIRMED ON CHR (Phase 4 `--stream` follow — CHR 7.23.1, 2026-06-30)
 

package/commands/api/README.md

@@ -114,7 +114,9 @@ vs `--query` distinction.
   before they were sent, keep the `transport/network` /
   `transport/connection-closed` retry. A mutating request that failed after it
   was sent carries the warning `transport/write-outcome-unknown`, in single-target
-  and fan-out mode alike.
+  and fan-out mode alike. A multi-statement `/execute` script refused with
+  `routeros/permission-denied` carries the same warning (#549); a single
+  refused statement, and a refused structured request, stay silent.
 - **`--stream` (or a `/listen` endpoint) is single-session** → `usage/fanout-not-supported` in
   fan-out mode. **`--raw` strips the envelope** → `usage/conflicting-flags` in
   fan-out mode (per-target envelopes can't be bare).
@@ -134,7 +136,8 @@ gate is `/console/inspect` — **not** `:put [:parse]`:
   does) answers normally on the same build. See the 7.12.2 finding in
   `AGENTS.md` (GH#343).
 - **Carve-out:** a script-shaped `POST /rest/execute` is a CLI string, not a path,
-  so structured inspect is `not-applicable` (`meta.validation.semantic`). It
+  so structured inspect does not apply and `meta.validation.semantic` is
+  absent. It
   follows the CLI-string pipeline instead: offline analysis, then live
   `:put [:parse ...]`, then run. An offline rejection is still a byte span with
   no connection; an offline pass or abstention continues to the device stage.
@@ -148,10 +151,11 @@ gate is `/console/inspect` — **not** `:put [:parse]`:
   unaffected — the result matchers are anchored, not substring.
 - Structured path requests are **not** offline-gated. The input is a path plus a
   body, not a CLI string, and an offline *path* gate collides with GH#211's
-  unlisted-path decision. On the success path `meta.validation.stages[]` is
-  absent there; on a `validation/*` rejection it is present and reports the
-  offline stage `skipped` with that reason, so the breakdown never implies an
-  analysis that did not run.
+  unlisted-path decision. `meta.validation.stages[]` reports the offline stage
+  `skipped` with that reason, on success and on a `validation/*` rejection
+  alike, so the breakdown never implies an analysis that did not run. On
+  success the device stage is `passed`, `semantic` is `true`, and there is no
+  `syntax` field, because no `:parse` ran (#535).
 
 `--validate=false` skips **both** stages of the preflight — one flag, one meaning
 (constitution: validation); RouterOS still re-validates writes server-side.

package/commands/api/examples.md

@@ -156,7 +156,7 @@ centrs api $R execute -X POST -f script=':put [/system/identity/get name]' --use
 ```
 
 Envelope: `ok: true`, `data` is string-shaped and contains the CHR identity;
-`meta.validation.semantic=not-applicable` (script, not a path) and
+`meta.validation.syntax=true` with no `semantic` field (script, not a path) and
 `meta.validation.stages` is `offline: passed` then live `device: passed` from
 `:put [:parse ...]`.
 

package/commands/execute/README.md

@@ -44,7 +44,14 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
   `isWriteShaped` is deliberately independent: script fallback for `[find]`, a
   positional id, or other non-`key=value` input never bypasses confirmation.
   Known read verbs are allowlisted; an unknown menu verb fails closed as a
-  write-shaped operation. In script mode every command head in a statement
+  write-shaped operation. A truly bare known-menu path (`/system/identity`,
+  example W6) is the one exception: structured mode proves the input is a
+  single path token, so it is console navigation — a no-op read — rather than
+  a command. The device still answers truthfully (`no such command` on the
+  APIs) and the envelope carries a steering tip naming the read that answers.
+  A bare no-argument *command* (`/system/reboot`) stays gated, as does
+  script-branch navigation (#387), where a later line may carry a relative
+  verb. In script mode every command head in a statement
   (the statement start and each `[…]` or `{…}` body) must be a read: its verb
   is the first word past the known menu prefix, so `/ip address print` is a
   read and `/user expire-password print` is not (examples W3). Script
@@ -283,7 +290,14 @@ A sent write is **never retried** (#448). Fan-out retries a target only for
 when the failure came before the request was sent (for example while it was
 being validated). A write that failed after it was sent may have run, so its
 error envelope, single-target or fan-out, carries the warning
-`transport/write-outcome-unknown`.
+`transport/write-outcome-unknown`. A multi-statement write refused with
+`routeros/permission-denied` carries the same warning: statements before the
+refused one may already have run (#549). Statements inside executed control
+scopes (`:if … do={…}`) and command substitutions (`[…]`) count; stored bodies
+(`source={…}`, `:global f do={…}`) do not, and a `/menu { … }` prefix is
+navigation, not a statement. A single refused statement did not
+run and stays silent, including one fed by a lone substitution
+(`remove [find …]`) or wrapped in a menu block.
 
 ## CMR clients through their controller (`--cmr`)
 
@@ -361,8 +375,9 @@ when the target is itself a CMR client.
   controller's own row through `run-script`, and rebooted a client through
   both. So a "reader" login on a 7.26beta1 controller is not read-only, and
   centrs' write gate (and `mcp=ro` on MCP) is the only gate. MikroTik
-  [says](https://forum.mikrotik.com/t/7-26beta-development-is-released/273582/139) 7.26beta2 refuses this for a `read` group; that is not yet
-  checked on a beta2 build. For a write,
+  [says](https://forum.mikrotik.com/t/7-26beta-development-is-released/273582/139) 7.26beta2 refuses this for a `read` group; #527 now carries
+  direct 7.26beta3 evidence that a restricted caller is refused, with the
+  first refusing release still unbracketed. For a write,
   centrs reads the login's own `/user` row and `/user/group` once (both are
   readable with just `read` + `api`). When the login lacks `write`, `test` or
   `reboot`, the result and the confirmation error carry
@@ -520,8 +535,13 @@ How it is wired:
   correctness issue — see `commands/terminal/README.md` for the optional fix).
 - **Delivery:** the UDP transport sends to `--host`/`--port` (default L2 broadcast
   `255.255.255.255:20561`); the device replies to our source IP:port, and the
-  in-packet MACs do the addressing. The CHR test points `--host`/`--port` at the
-  loopback L2 bridge.
+  in-packet MACs do the addressing. The device answers only broadcast delivery
+  (unicast gets no reply), and only when the in-packet *source* MAC is the
+  egress interface's real MAC — a synthetic source gets no reply on hardware
+  (CHR answers it, so the suite cannot catch a wrong source). With the default
+  host centrs sprays per-interface discovery with real MACs; with an explicit
+  `--host <directed-broadcast>` it resolves the owning interface's MAC. The CHR
+  test points `--host`/`--port` at the loopback L2 bridge.
 
 Protocol selection: an unresolved MAC target auto-selects mac-telnet (covered by
 `test/unit/execute.test.ts`); callers wanting IP-level execution opt into ARP

package/commands/execute/examples.md

@@ -67,9 +67,9 @@ centrs execute $R ':local a true; :if ($a = true) do={:put [/system/identity/get
 
 Envelope: `ok: true`, `data` is string-shaped (`data.output` or `data.ret`) and
 contains the CHR identity name, `meta.via=rest-api`, and
-`meta.validation.syntax=true`. `meta.validation.semantic` is absent or marked
-`not-applicable` because `/console/inspect` validates path-shaped commands, not
-arbitrary script expressions. The `$a` variable must survive the validation
+`meta.validation.syntax=true`. `meta.validation.semantic` is absent because
+`/console/inspect` validates path-shaped commands, not arbitrary script
+expressions (#535). The `$a` variable must survive the validation
 wrapper: if that outer string expands it before `:parse`, this example fails even
 though RouterOS accepts the original command.
 
@@ -490,8 +490,8 @@ Envelope: `ok: false`, `error.code=validation/package-missing`,
 `error.context.packages` names the published package, the remediation points at
 `/system/package/print` and never at the syntax, and `error.position` and
 `error.context.detail` keep RouterOS's own column and words. V5–V7 all report
-`meta.validation.syntax=false`. `semantic` is absent, or `not-applicable` for
-the script-shaped `/container print` (GH#435).
+`meta.validation.syntax=false`, and `semantic` is absent because the
+name-level check was never asked (GH#435, #535).
 
 ### V6. A menu no RouterOS build has is an unknown path
 
@@ -633,6 +633,25 @@ This is a grounding version, not an introduction boundary. Unknown or
 ambiguous output-file prefixes stay write-shaped until the device resolves
 them.
 
+### W6. A bare menu path needs no confirmation and answers with a steering tip
+
+```bash
+centrs execute $R '/system/identity' --via rest-api --username $U --password $P
+```
+
+No `--yes` gate: a truly bare known-menu path is console navigation, a no-op
+read, and structured mode proves the input is a single path token with no
+follow-up. The device still answers truthfully — REST reports
+`routeros/request-failed`, native API `routeros/api-trap`, both carrying
+RouterOS's own `no such command` — and the envelope carries
+`tip/execute-bare-menu-path`, naming `/system/identity/print` (or
+`centrs retrieve $R /system/identity`) as the read that answers. A bare
+no-argument *command* such as `/system/reboot` stays write-shaped and still
+requires confirmation.
+
+`test/integration/execute-write-gate.test.ts` proves the gate stays open for
+navigation and shut for no-arg writes, on REST and native API.
+
 ### R1. A post-validation `/execute` rejection fails the overall envelope
 
 ```bash