@tikoci/centrs 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -8,6 +8,111 @@ documenting cross-cutting shifts that affect contributors and consumers.
 
 ## Unreleased
 
+## 0.1.3 — 2026-07-06
+
+Patch release. `@tikoci/centrs@0.1.3`.
+
+### Added
+
+- **`api` command over rest-api + native-api is `CHR-passed`.** `centrs api`
+  brings a `gh api`-style structured passthrough to both transports, and folds
+  the old standalone `stream` command into `api --stream` (native-api only,
+  `--listen` alias): a `NativeApiSession.listen()` reader with `/cancel`
+  support emits NDJSON frames plus a run summary. Grounded against real CHR
+  7.23.1.
+- **Multi-target fan-out is uniform across `api`, `retrieve`, `execute`, and
+  `transfer`.** A shared `expandCdbSelection` + `runFanout` + `fanoutExitCode`
+  core (extracted once, consumed by all four commands) lets any command take a
+  CDB selector and run over every matching device. The positional boundary
+  that ends the selector differs per command (final positional for
+  `api`/`retrieve`, `--` for `execute`, the verb keyword for `transfer`);
+  `terminal` and `api --stream` explicitly reject `N > 1` selections since
+  neither has a sane multi-target framing.
+- **`settings` command (`print` / `get` / `set` / `reset`).** A managed-key
+  registry for the real `CENTRS_*` environment keys backs an atomic
+  `centrs.env` writer: `set` validates per key, canonicalizes booleans to
+  `1`/`0` on disk, warns (never blocks) on consequential values
+  (`insecure=true`, `transfer-via=ftp`), and never partially writes on a
+  validation failure; `reset` deletes the managed line rather than blanking it
+  (a blank value would itself mean "set to empty" for a bash-sourced file) and
+  leaves foreign lines/comments untouched. Bare `centrs settings` behaves like
+  `print` regardless of TTY. Four new error/warning codes
+  (`settings/reserved-key`, `settings/unknown-key`,
+  `settings/consequential-value`, `settings/skip-env-file-active`) plus
+  `internal/settings-failed`, all cataloged. `CHR-passed` via 32
+  fixture-backed integration examples.
+- **Device GPS: lat/lon/altitude storage + `--near` / `--bbox` geo
+  predicates.** `centrs devices` now stores GPS coordinates per device
+  (lat-first ordering, chosen so agents guess the field order correctly) and
+  supports proximity
+  (`--near`) and bounding-box (`--bbox`) selection predicates. `CHR-passed`
+  via fixture-backed integration coverage.
+- **Registry⇄MATRIX drift guard + "did you mean?" flag errors.** A CI-checked
+  guard keeps the command/protocol registry and `docs/MATRIX.md` from
+  silently drifting apart; unrecognized CLI flags now suggest the closest
+  known flag instead of a bare rejection.
+- **GitHub Pages: published API reference + error catalog.** `typedoc` output
+  and the generated error-code catalog now publish to GitHub Pages on push.
+
+### Fixed
+
+- **Windows unit-test portability for `settings` and MNDP.** Path-separator
+  and related platform assumptions in the `settings` and MNDP unit suites are
+  now Windows-safe (#170).
+- **A real CodeQL-caught ReDoS in the device GPS geo-predicate parser**, fixed
+  rather than suppressed.
+
+### Changed
+
+- **CodeQL house-rules pack promoted to the default run**, alongside CodeRabbit
+  review-tone tuning and a reduced GitHub-checks timeout (15 → 7 minutes).
+
+## 0.1.2 — 2026-06-26
+
+Patch release. `@tikoci/centrs@0.1.2`.
+
+### Added
+
+- **`btest` TCP multi-connection fan-out is `CHR-passed`.** `centrs btest
+  --connection-count N` now realizes the full fan-out: the client reads the
+  session token from the primary's OK handshake and opens `N-1` additional TCP
+  data connections, each sending the grounded secondary-join
+  (`[token:u16 BE][0x02][0…]`). All connections drive into one shared
+  `BandwidthCounters` so throughput aggregates. Wire format confirmed
+  byte-for-byte against RouterOS 7.23.1 (the server sends a 4-byte HELLO per
+  connection then waits for all to join before streaming — sequential opens must
+  not block on a reply, or the first secondary deadlocks the server). Unauthenticated
+  TCP fan-out works end-to-end; authenticated (EC-SRP5) sessions stay single-stream
+  and warn when the realized `activeConnections` falls short of the requested count.
+  `BtestRunSummary` / `BtestClientData` gain an `activeConnections` field.
+  Grounded via unit tests (secondary-join byte format, loopback fan-out) and
+  integration example 11 on real CHR (4 connections open, data flows on each).
+
+### Fixed
+
+- **`btest` UDP client receive reported 0 bps.** The UDP socket was bound with
+  `connect()` (filtering by remote address/port), which dropped the
+  bandwidth-server's probe packets because they arrive from the server's data
+  port, not the control port. The socket is now unconnected; `--remote-udp-tx-size`
+  emits a warning when unset (needed by the server-push direction only).
+  UDP `receive` and `both` cycles are now CHR-gated on real RouterOS (rx ≈ 474 KB
+  in CI).
+- **`btest --connection-count` was silently ignored.** The count was validated and
+  accepted but never encoded into command byte 3 of the client hello, so RouterOS
+  always saw `count=0` and opened a single stream. The value is now threaded through
+  `BtestClientSessionOptions` → `clientHandshake`. A
+  `routeros/btest-connection-count-single-stream` warning fires for
+  `connection-count > 1` sessions that fall back to one stream (e.g. EC-SRP5 auth).
+- **`btest direction=both` TX was unbounded, starving RX.** In TCP `both` the client
+  ran no status reader, so TX had no feedback, saturated the link, and collapsed
+  server→client RX. The `tcpRxLoop` now demuxes embedded 12-byte status frames
+  in-place by their structural marker (`0x07 ?? 00 00`) and passes them through the
+  shared `applyStatusFeedback` / `adaptTxFromStatus` gate used by
+  `tcpStatusReaderLoop`. A per-frame plausibility guard (CPU byte ≤ 100; sane
+  sequence ceiling) filters false matches from `--random-data` bulk streams.
+  Grounded: a CHR `both` run fires 5 feedback events (server bytesReceived
+  78840 → 643860) and paces TX; RX is sustained instead of collapsing.
+
 ## 0.1.1 — 2026-06-22
 
 Patch release. `@tikoci/centrs@0.1.1`.
@@ -214,8 +319,8 @@ First published pre-release (odd minor → npm `next`). `@tikoci/centrs@0.1.0`.
     result envelope, error model + URL scheme, settings precedence, identity,
     protocol selection, done = CHR-passed).
   - `docs/MATRIX.md` — command×protocol grid; the only status surface.
-  - `commands/<name>/{README,examples}.md` — per-command design and
-    executable example list that gates "done."
+  - `commands/<name>/README.md` and `commands/<name>/examples.md` —
+    per-command design and executable example list that gates "done."
 - Done definition codified in
   `.github/instructions/done-definition.instructions.md`: a feature is done
   when its examples are green on real CHR via `bun run test:integration`.

package/GLOSSARY.txt

@@ -25,6 +25,11 @@
 #   https://github.com/tikoci/restraml
 # %lsp-routeros-ts: RouterOS parser and language-server utilities.
 #   https://github.com/tikoci/lsp-routeros-ts
+# Language Server Protocol — the "lsp" in lsp-routeros-ts, referenced as a
+# grounding source for /console/inspect client patterns (e.g. commands/api).
+lsp
+# RouterOS maximum transmission unit property (e.g. mtu, actual-mtu).
+mtu
 # %donny: Dude/discovery grounding for RouterOS device inventories.
 #   https://github.com/tikoci/donny
 # %m2ir: protocol IR (WinBox, nova messages) + the declarative schema-as-data
@@ -89,6 +94,8 @@ datagram
 davidanson
 DDNS
 defconf
+demux
+demuxes
 dogtail
 donny
 dotenv
@@ -132,6 +139,7 @@ MNDP
 NAND # NAND flash memory; write-back caches file writes up to ~40s on some MikroTik boards
 netmiko # [Multi-vendor library to simplify Paramiko SSH connections to network devices](https://github.com/ktbyers/netmiko)
 netwatch
+nullglob # bash shopt that makes an unmatched glob expand to zero words instead of the literal pattern
 npk # MikroTik package format
 nvme-over-tcp # supported by RouterOS **with** rose-storage.npk extra-package
 OID
@@ -141,11 +149,13 @@ PRGA
 proplist
 pywinauto
 QML
+qll # CodeQL library file extension (.qll), e.g. CleartextLoggingCustomizations.qll
 qmljsdebugger
 quickchr
 RAML
 readcdb
 remotehub
+retarget
 restraml
 romon
 ros
@@ -153,12 +163,15 @@ rosetta
 routeros
 routeros-skills
 rsc # RouterOS script / export file extension (.rsc)
+SARIF # Static Analysis Results Interchange Format; CodeQL's code-scanning analysis download format
 scp
 scriptability
 scriptable
+shopt # bash builtin for toggling shell options (e.g. nullglob)
 Sikuli
 SikuliX
 skillcheck
+startswith # jq builtin filter that tests whether a string begins with a given prefix
 SNMP
 SPI
 SRP
@@ -176,6 +189,7 @@ TIKOCI
 tiktui
 TLV
 traceroute
+tostring # jq builtin filter that renders a value as its JSON string representation
 tsc
 tzsp
 TZSP
@@ -418,3 +432,76 @@ trippable
 # btest integration-test fixtures.
 btestuser
 btestpass
+
+# RouterOS scripting builtin referenced in commands/api grounding notes
+# (:toarray coerces a comma string into an array; explains the inspect path form).
+toarray
+
+# Logic shorthand ("if and only if") used in api write-gate doc comments; cspell's
+# markdown dictionary knows it but the TypeScript one does not.
+iff
+
+# GitHub Pages build vocabulary (scripts/build-pages-site.ts, pages.yaml)
+# typedoc/pandoc: the API-reference generator and the markdown->HTML converter
+#   the Pages build chains together. gfm: GitHub-Flavored Markdown, pandoc's
+#   input format for the error pages. larr: the "←" left-arrow HTML entity
+#   in the back-to-docs link. nojekyll: the marker file that disables GitHub
+#   Pages' Jekyll processing for an Actions-deployed artifact. extensionless:
+#   describes the `details_url` contract (docs/errors/README.md) — no `.html`.
+typedoc
+pandoc
+gfm
+larr
+nojekyll
+extensionless
+# nothrow: Bun Shell's `$` method to disable throwing on a non-zero exit
+# (scripts/agent-check.ts), so the caller can inspect output either way.
+nothrow
+
+# check-command spec vocabulary (commands/check/README.md, examples.md)
+# TikTOML: centrs-owned readable device-inventory format (#137); check's
+#   metadata feeds it. routerboard: RouterBOARD firmware/hardware menu
+#   (/system/routerboard). rscmd: the tikbook RouterOS command-notebook file
+#   extension (.rscmd), the format the check spec was grounded against.
+TikTOML
+routerboard
+rscmd
+# RTT: round-trip time, the host->router connect-latency reach signal. tojson: the
+#   /system/script helper (:serialize to=json) the batched execute reads reuse.
+#   qrcode: the /ip/cloud vpn-wireguard-client-config-qrcode field token (redacted
+#   by the cloud check, referenced when documenting redaction).
+RTT
+tojson
+qrcode
+
+# Device GPS vocabulary (issue #146, commands/devices/README.md "Location /
+# GPS", src/resolver/geo.ts). MSL/AGL: the two supported altitude-type vertical
+#   datums (mean sea level / above ground level); stored case-insensitively but
+#   normalized to upper case. EPSG: the geodetic coordinate-reference-system
+#   registry (EPSG:4326 = WGS84 lat/lon), cited for the lat-first ordering
+#   rationale. bbox: the --bbox geo selector (bounding box). wgs: WGS84, the
+#   geodetic datum GPS coordinates use; appears only as a deliberately-invalid
+#   --altitude-type value in tests/examples. antimeridian: the 180° meridian a
+#   --bbox may not cross in v1. GEOSEARCH: the Redis command whose m/km/mi/ft
+#   radius-unit vocabulary --near borrows. IUGG: the geodesy union whose mean
+#   Earth radius the haversine uses. SFO/OAK: airports used as a known-distance
+#   haversine fixture in tests. ele/GPX: `ele` is GPX's altitude element, kept as
+#   an input alias for `altitude` (GPX = the GPS Exchange Format). Geolocation:
+#   the W3C Geolocation API, cited (with ISO 6709 / EPSG / IETF geo:) for why
+#   `altitude` — not `elevation` — is the canonical field name.
+MSL
+msl
+AGL
+agl
+Agl
+EPSG
+bbox
+wgs
+antimeridian
+GEOSEARCH
+IUGG
+SFO
+sfo
+ele
+GPX
+Geolocation

package/README.md

@@ -4,6 +4,12 @@
 CLI (with MCP, TUI, and HTTP proxy frontends planned) for talking to MikroTik
 RouterOS devices through a regularized, validated interface.
 
+Preview builds are published on npm. To inspect the CLI without installing it:
+
+```bash
+bunx @tikoci/centrs --help
+```
+
 It is a **friendly conduit**, not a high-level configuration abstraction. It
 helps humans and agents reach RouterOS over the right protocol, with the right
 credentials and ports, and validates RouterOS-shaped commands before running
@@ -11,9 +17,12 @@ them. It does **not** hide RouterOS behind helpers like `createVlanOnBridge()`
 — you still speak RouterOS. Validation and structured diagnostics are the
 product; without them this would just be a worse `curl`.
 
-> **Status:** early and in active development. The library, device registry, and
-> first MCP server phases are CHR-verified; the CLI is wired (`coded`); encrypted-CDB
-> writes are still blocked, and the TUI/proxy frontends are planned.
+> **Status:** early npm preview, active development. `@tikoci/centrs` is
+> published on npm, but command flags and envelopes may still change before a
+> stable release. Check current dist-tags with
+> `npm view @tikoci/centrs dist-tags --json`. The library, device registry, and
+> first MCP server phases are CHR-verified; the CLI is wired (`coded`);
+> encrypted-CDB writes are still blocked, and the TUI/proxy frontends are planned.
 > `docs/MATRIX.md` is the single source of truth for what works today — treat
 > anything not green there as not-yet-shipped.
 
@@ -32,8 +41,8 @@ product; without them this would just be a worse `curl`.
 | Command    | Purpose |
 | ---------- | ------- |
 | `retrieve` | Read RouterOS state over REST/native API and SNMP OID/MIB values. |
-| `stream`   | Follow live RouterOS output (`print follow`/monitor/sniffer) as an NDJSON stream of envelopes. |
 | `execute`  | Run RouterOS CLI-shaped read/write commands (add/set/remove) over native API/REST/L2 surfaces. |
+| `api`      | Structured RouterOS API passthrough (gh-api style): one command per operation, structured in/out, can write, over REST or native API. Open-ended follow is `api … --stream` (native API; NDJSON). |
 | `terminal` | Open an interactive console, primarily SSH or MAC-Telnet. |
 | `check`    | Probe reachability and management protocol availability. |
 | `devices`  | View and maintain the CDB-backed device registry (the only writer). |
@@ -104,16 +113,23 @@ CDB tags, and `devices set` refuses to put them there. Unknown keys produce a
 `cdb/unknown-option` warning and are ignored, so a stray `=` in human prose
 never breaks anything.
 
-Settings resolve lowest-to-highest: **built-in defaults → project config →
-comment-kv → `CENTRS_*` env → CLI flag / API arg.** Every result envelope
-reports which source won each setting under `meta.settings`, so you can always
-see *why* a given port or transport was chosen.
+Settings resolve lowest-to-highest: **built-in defaults → user config file
+(`centrs.env`) → comment-kv → `CENTRS_*` env → CLI flag / API arg.** Every
+result envelope reports which source won each setting under `meta.settings`,
+so you can always see *why* a given port or transport was chosen.
 
 ### Groups, discovery, and the MCP allowlist all ride on the CDB
 
 - **Groups** are CDB-native: an entry's `group` field is just a string, and
   `--group prod-edge` fans a single command out to every entry that shares it.
-  There is no separate group-definition file.
+  There is no separate group-definition file. Groups are one selector in a
+  **uniform fan-out grammar** shared by `api`, `retrieve`, `execute`, and
+  `transfer`: mix `<router>` positionals, repeatable `--group`/`--where
+  <attr>=<value>`, `--all`, and `--default` (de-duped by CDB record index). Every
+  fan-out returns the locked `FanoutData` envelope (per-target results, not
+  metadata) with a granular exit code (`0` all ok / `2` partial / `1` all failed);
+  a multi-target write is gated once by `--yes` naming the blast radius. See
+  `docs/CONSTITUTION.md` (Target selection grammar).
 - **Discovery** writes back into the CDB: `discover --save` records MNDP
   neighbors as new entries tagged `group=discovered` with a `source=mndp`
   marker — hints to curate, not authoritative inventory.

package/SECURITY.md

@@ -14,14 +14,14 @@ Please include the affected files or workflow, reproduction details, and impact.
 
 The repository's [Security tab](https://github.com/tikoci/centrs/security) is the live source of current alerts and advisories. This section describes *what* checks run and *why*, so the doc stays meaningful even when the badge is at 0.
 
-- **CodeQL** — repo-managed workflow at [`.github/workflows/codeql.yaml`](.github/workflows/codeql.yaml) with config [`.github/codeql-config.yml`](.github/codeql-config.yml). Query suite: `security-and-quality` (security-extended + code-quality). Languages: `javascript-typescript`, `actions`. Schedule: push to `main`, pull requests to `main`, weekly cron, and manual dispatch.
-- **Code Quality (AI findings, preview)** — intended to be enabled in GitHub. [`.github/workflows/codeql.yaml`](.github/workflows/codeql.yaml) includes a non-failing forward-compat probe for a future AI-findings API. AI findings are noisy and self-contradicting; we accept the noise because the second-opinion catches real issues that the static suite misses. Steady-state goal is 0 open findings. False positives are dismissed via the GitHub UI with a written justification — that text is the audit-log contract.
+- **CodeQL** — repo-managed workflow at [`.github/workflows/codeql.yaml`](.github/workflows/codeql.yaml) with config [`.github/codeql-config.yml`](.github/codeql-config.yml). Query suite: `security-and-quality` (security-extended + code-quality) plus a small custom pack, [`.github/codeql-house-rules/`](.github/codeql-house-rules/), that structurally checks a handful of repo-specific invariants (currently: `apiFanout` must call its named protocol/validation gates) — see `.github/instructions/github-security-quality.instructions.md` for scope and the verify-before-promote discipline for adding more rules there. Languages: `javascript-typescript`, `actions`. Schedule: push to `main`, pull requests to `main`, weekly cron, and manual dispatch.
+- **Code Quality (AI findings, preview)** — confirmed active in GitHub as of 2026-07-03 (not just "intended"; see [issue #166](https://github.com/tikoci/centrs/issues/166)). [`.github/workflows/codeql.yaml`](.github/workflows/codeql.yaml) includes a non-failing forward-compat probe for a future AI-findings API. AI findings are noisy and self-contradicting; we accept the noise because the second-opinion catches real issues that the static suite misses. Steady-state goal is 0 open findings. False positives are dismissed via the GitHub UI with a written justification — that text is the audit-log contract. Side effect: GitHub's own Code Quality scan runs in parallel with our Advanced Setup and posts a same-named `Analyze (javascript-typescript)` check, so PR checks lists show it twice — cosmetic, tracked in #166, not a required check either way (see issue #118).
 - **Dependency review** — not enabled. GitHub dependency review follows dependency-graph ecosystem support, and this Bun-only repository currently does not have a supported lockfile for that gate.
 - **Dependabot security updates** — enabled and configured in [`.github/dependabot.yaml`](.github/dependabot.yaml).
 - **Secret scanning** — enabled in GitHub, with push protection.
 - **Private vulnerability reporting** — enabled via GitHub Security Advisories.
 
-Some GitHub Security tab data, especially Code Quality AI findings, is not currently available through stable unauthenticated APIs. Human review in the GitHub UI remains part of the security workflow.
+Some GitHub Security tab data, especially Code Quality AI findings, is not reachable through the default workflow `GITHUB_TOKEN` (`repos/{owner}/{repo}/code-quality/findings` 403s there even with `security-events: read`) — it does respond with an elevated/owner-scoped token, but no findings have been recorded yet to confirm the response shape end-to-end (see #166). Human review in the GitHub UI remains part of the security workflow until that's wired up.
 
 ## Supported versions
 

package/commands/AGENTS.md

@@ -18,8 +18,9 @@ README's "Status" line must agree with it.
 
 ## Verb vocabulary
 
-Commands are centrs **verbs** (`retrieve`, `stream`, `execute`, `devices`,
-`discover`, `check`, `terminal`, `settings`), never one tool per RouterOS command. Sub-verbs and their
+Commands are centrs **verbs** (`retrieve`, `execute`, `api`, `devices`,
+`discover`, `check`, `terminal`, `settings`), never one tool per RouterOS command. Open-ended follow
+is folded into `api --stream` (no separate `stream` verb). Sub-verbs and their
 aliases are canonical across CLI / API / MCP:
 
 | Canonical | Aliases          | Meaning                                  |

package/commands/api/AGENTS.md

@@ -0,0 +1,212 @@
+# commands/api — local constraints + grounded RouterOS facts
+
+This file is the **durable home** for the RouterOS API-behavior facts the `api`
+command depends on. It exists so the knowledge survives context resets: a fresh
+agent picking up any `api` phase reads this first. Add a fact here only with a
+source (a doc URL, a `tikoci/*` project, or a CHR run); follow the global
+grounding discipline — one CHR result is a signal, reproduce before treating it as
+fact.
+
+Read order for any `api` work: `docs/CONSTITUTION.md` → `commands/api/README.md` →
+`commands/api/examples.md` → this file.
+
+## Local constraints
+
+- `api` is the structured one-command-per-operation surface (the verb trichotomy
+  in `README.md`). It must not grow code-block / multi-command behavior — that is
+  `execute`'s job.
+- Reuse the shared cores, do not fork: `src/core/inspect.ts` (the
+  `/console/inspect` client) and `src/core/fanout.ts` (the fan-out engine).
+- Honor `--via` literally; never silently downgrade transport.
+
+## Grounded facts (doc sources)
+
+REST API — <https://help.mikrotik.com/docs/spaces/ROS/pages/47579162/REST+API> ·
+native API — <https://help.mikrotik.com/docs/spaces/ROS/pages/47579160/API> ·
+inspect-client TS patterns — `tikoci/lsp-routeros-ts`
+(`server/src/routeros.ts` `InspectRequest`, `server/src/validation.ts`).
+
+- **HTTP method map (REST):** `GET`→print, `PUT`→add (**create**), `PATCH`→set,
+  `DELETE`→remove, `POST`→universal (run any console command). PUT — not POST — is
+  RouterOS's create.
+- **Multi-frame results: bounded → array; open-ended → native `/listen` only.**
+  *Nuance (do not over-read the REST docs).* RouterOS REST **does** run
+  `duration=` / `monitor` commands — it regularizes the native `!re` frames into a
+  JSON **array of `.section` records** and returns the whole array in one response,
+  bounded by the **60 s** REST cap (a command asked to run longer terminates early
+  with an error). Native has **no** such cap. So a `duration=`/`monitor` command is
+  an **ordinary bounded `api` call** that returns a `.section` array on both
+  transports (native's `talk()` accumulates the `!re` until `!done`) — **not**
+  NDJSON. The only thing that needs the NDJSON streaming path is **open-ended
+  follow** (native `/listen`, which never sends `!done`); REST genuinely cannot do
+  open-ended follow. ⇒ `--listen` (open-ended) is native-only; `duration=` commands
+  are normal one-shot calls. (CONFIRMED below.)
+- **`/listen` semantics.** Emits `!re` on change; a deleted/disappeared item's
+  `!re` carries the dead flag (docs say `=.dead=yes`; **CHR 7.23.1 sends
+  `.dead=true`** — see CONFIRMED below); it never self-terminates. Cancel with
+  `/cancel tag=<listen-tag>` (the `/cancel` carries its own `.tag`); the listener
+  then gets `!trap … message=interrupted` followed by `!done`.
+- **Query.** REST `.query` words are **identical to native `?` words minus the
+  `?` prefix** (CONFIRMED below). Forms: eq `name=val`; comparison `>name=val` /
+  `<name=val` (operator **before** the name); has-property `name`; absence
+  `-name`; stack ops `#!` (NOT top), `#&` (AND), `#|` (OR). Multiple words with no
+  stack op are **implicitly AND-ed**. See the centrs mapping section below.
+- **Proplist.** REST `.proplist` accepts `"name,type"` or `["name","type"]`.
+  Native: `=.proplist=name,type`.
+- **Object id.** Set/remove by id: REST id-in-URL (`PATCH /rest/ip/address/*1`),
+  native `=.id=*1` word. **No native get-one-by-id shorthand** — use
+  `print ?.id=*1`. REST has the convenience `GET /rest/ip/address/*1` → a single
+  object; native maps it to `print ?.id=*1`.
+- **`/console/inspect` request modes** (`InspectRequest` in lsp): `request ∈
+  {child, completion, highlight, syntax}`, with `input?`, `path?`, `.proplist?`,
+  `.query?`. `child` lists menus/args (path + attribute validity); `completion`
+  + `input=` yields allowed values (tips/warnings); `highlight` + `input=` is
+  token-level error detection (lsp's primary validator); `syntax` is the parse
+  tree.
+
+## Query mapping (centrs `--query` / `--raw-query`)
+
+Two layers, both grounded above:
+
+- **`--query` / `--filter`** — structured convenience, **AND-combined** (RouterOS
+  default), repeatable. Each maps to one query word:
+  - `name=value` → `name=value` (eq)
+  - `name!=value` → two words `name=value`, `#!` (eq then NOT-top)
+  - `name>value` / `name<value` → `>name=value` / `<name=value`
+  - `name` (no `=`) → `name` (has-property)
+  Multiple `--query` emit their words in order; RouterOS's implicit AND applies (no
+  `#&` injected). `--query` cannot express OR or arbitrary stacks — that is
+  `--raw-query`.
+- **`--raw-query <word>`** — power-user escape hatch, repeatable. Each value is a
+  **verbatim RouterOS query word** (absence `-name`, OR `#|`, AND `#&`, NOT `#!`,
+  or any `>`/`<`/`=` form). Emitted as-is: a `.query` element over REST, a
+  `?`-prefixed word over native. centrs does **not** parse or reorder raw words —
+  the caller owns the stack. When `--query` and `--raw-query` are both given, the
+  structured words are emitted first, then the raw words, in order.
+
+This keeps the common case (`--query type=ether`) clean while giving full
+stack-language access without centrs modelling the whole query grammar.
+
+## CONFIRMED ON CHR (Phase 0 grounding spikes — CHR 7.23.1, 2026-06-29)
+
+Probes: scratchpad `api-grounding-spike.ts` (listen/CRUD/execute) and
+`api-grounding-spike2.ts` (duration/monitor + query forms + inspect path). Raw
+native codec for the listen probe; `fetch` for REST; `connectNativeApi().talk()`
+for native.
+
+- **CONFIRMED — native `/listen` + `/cancel`.** `/ip/address/listen .tag=2`
+  emits an `!re tag=2` carrying the **full new record** on add; on delete it emits
+  a **minimal** `!re tag=2 { ".id":"*3", ".dead":"true" }`. **Correction to the
+  docs:** the wire flag is **`.dead=true`**, not `=.dead=yes`. `/cancel =tag=2
+  .tag=3` yields `!trap tag=2 {category:2, message:interrupted}`, then `!done
+  tag=3` (the cancel) **and** `!done tag=2` (the listen closes). Modern plaintext
+  `/login` returns a bare `!done` (no challenge) on 7.23.1.
+- **CONFIRMED — native CRUD by id.** `add` returns the new id in `=ret=`; `set`
+  and `remove` via `=.id=<id>` succeed with zero `!re` (only `!done`); get-one is
+  `print ?.id=<id>` → exactly one record. `numbers=` is **not** needed (that is
+  execute's CLI idiom, not the API's).
+- **CONFIRMED — query + proplist.** Native `/interface/print ?type=ether` filters
+  server-side; `=.proplist=address,interface` returns only those keys. REST
+  `POST /rest/interface/print {".query":["type=ether"],".proplist":"name,type"}`
+  → `200 [{"name":"ether1","type":"ether"}]` (a complete **array**, not a stream).
+- **CONFIRMED — duration/monitor returns a bounded `.section` array (both
+  transports).** `POST /rest/interface/monitor-traffic {interface:ether1,
+  duration:"5s"}` → `200`, ~5.0 s, a **JSON array of 5 records** keyed
+  `.section:"0".."4"` (each `…-bits-per-second` etc.). The native
+  `/interface/monitor-traffic duration=2s` returns the same frames via `talk()` (2
+  records, each with `.section`) before `!done`. So duration commands are ordinary
+  bounded calls, **not** NDJSON. (Corrects the first spike's over-strong "REST does
+  not support continuous commands" reading; the `/rest/interface/monitor` 400 there
+  was just a wrong command path — `monitor-traffic` is the real menu.) The 60 s
+  unbounded cap stays doc-grounded — not worth a 60 s CI wait to reproduce.
+- **CONFIRMED — `/console/inspect` `path` is array-typed; pass COMMA tokens, not a
+  slash command.** `request=child path=system,license` → children `license:dir,
+  export:cmd, generate-new-id:cmd, get:cmd, print:cmd, renew:cmd`; the **slash**
+  forms (`system/license`, `/system/license`) return **nothing**. (This is why the
+  first spike's license probe was empty — wrong path form.) **Why (rationale, not
+  yet re-spiked):** RouterOS's inspect `path` argument is internally an **array**
+  type — a comma string like `ip,address,set` is `:toarray`-split into
+  `["ip","address","set"]`, the menu walk inspect expects. A `/`-prefixed
+  command-style string is **not** an array and isn't split, so it matches no menu.
+  A JSON **array** body over REST (`{"path":["ip","address"]}`) should therefore
+  work too — **plausible but unconfirmed; do not rely on it.** The contract centrs
+  uses is the **comma-joined string** (confirmed; what both `retrieve` and
+  `execute` already build via their duplicate `join(",")` helpers — the Phase-1
+  `src/core/inspect.ts` is the single home for it). And **`renew` is a `cmd`
+  node** → `/system/license/renew` is a write/command, confirming the "streaming ≠
+  read-only" rule concretely.
+- **CONFIRMED — `.query` forms (REST word == native `?`-word minus `?`).** On
+  `/interface/print` (2 interfaces: ether, loopback): eq `type=ether` → 1; ne
+  `["type=ether","#!"]` → loopback; OR `["type=ether","type=loopback","#|"]` → 2;
+  gt `[">actual-mtu=1000"]` → 2; has `["running"]` → 2; absence `["-running"]` →
+  0; implicit-AND `["type=ether","running"]` → 1. Identical results native
+  (`?`-prefixed). REST license singleton: `GET /rest/system/license` →
+  `{"level":"free","system-id":"…"}`.
+- **CONFIRMED — `POST /rest/execute` modes.** With `"as-string":""` it runs
+  **synchronously** → `{"ret":"CHR"}`. **Without** `as-string` it is **fire-and-
+  forget**: it schedules a job and returns the **job id** (`{"ret":"*18"}`, HTTP
+  200) — a `:error` does **not** surface synchronously. ⇒ `api`'s script-POST must
+  send `as-string` (reuse execute's `restPost("/execute",{script,"as-string":""})`,
+  `adapter.ts:199`) so output/errors are synchronous; the bare async-job form is
+  not the default.
+- **RESOLVED — `/system/license`** (was inconclusive in spike 1 due to the slash
+  path; see the COMMA-path finding above). Independently, `isApiMutating` keys the
+  write gate on the method/verb, so even an async/streamable write like
+  `/system/license/renew` confirms regardless.
+
+## CONFIRMED ON CHR (Phase 2+3 integration — CHR 7.23.1, 2026-06-29)
+
+Validated by `test/integration/api.test.ts` (rest, examples 1–20, 98 assertions)
+and `test/integration/api-native.test.ts` (native, N1–N8, 31 assertions), both
+green on CHR 7.23.1.
+
+- **CONFIRMED — native `/execute` supports `=as-string=` for synchronous output.**
+  Native `talk /execute =script=…` **without** `as-string` is **fire-and-forget**:
+  it schedules a job and returns the **job id** in `=ret=` (observed `"*31"`), not
+  the script output — exactly the REST behavior. Adding `=as-string=` (empty value)
+  makes it run synchronously and return the captured output, identical to REST
+  `/rest/execute {as-string}`. **This corrects `src/execute.ts`'s long-standing
+  assumption that native script mode is unsupported** (execute still blocks it; the
+  `api` path proves native `/execute =as-string=` works). `api` always sends
+  `as-string` for a script run on both transports.
+- **CONFIRMED — native CRUD re-mapping to rest-style.** `add` returns the new id
+  only in the `!done` `=ret=` word → centrs re-maps it to `{".id": ret}` (REST PUT
+  returns the full created object with `.id`; native gives just the id). `set`/
+  `remove` reply with a bare `!done` (no `!re`) → no body → centrs surfaces `null`.
+  get-one is `print ?.id=<id>` → exactly one record → returned as a single object
+  (not a 1-element array). All grounded in `restStyleMutationData` /
+  `restStyleRunData` (`src/protocols/adapter.ts`).
+- **CONFIRMED — REST `monitor-traffic` over the `api` path returns a `.section`
+  array.** `POST /rest/interface/monitor-traffic {interface,duration}` →
+  `[{".section":"0",…}, {".section":"1",…}]` (re-confirms the spike-2 finding via
+  the real `api` REST adapter). It is a command (terminal verb `monitor-traffic`,
+  not `print`/`get`), so it is a `POST` and **write-classed** → needs `--yes`.
+- **CONFIRMED — the inspect gate over both transports.** Path existence
+  (`request=child` empty ⇒ `validation/unknown-path`) and add/set attribute
+  validity (`request=child`+`completion` ⇒ `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"`.
+
+## CONFIRMED ON CHR (Phase 4 `--stream` follow — CHR 7.23.1, 2026-06-30)
+
+Validated by `test/integration/api-listen.test.ts` (L1–L4) on CHR 7.23.1.
+`--stream` is the primary flag; `--listen` is an alias; a `/listen` endpoint
+infers both. Native-api only (REST's 60s cap → `transport/capability-unsupported`).
+
+- **CONFIRMED — `NativeApiSession.listen()` + `/cancel` end-to-end.** Opening
+  `/ip/address/listen` (own `.tag`) and adding an address over REST yields an
+  `!re` frame; stopping (`--count`/`--duration`/Ctrl-C) sends `/cancel =tag=<t>
+  .tag=<n>` and the listen closes via the `interrupted` trap (category 2) then
+  `!done` — the generator ends **without** throwing (the interrupted trap is the
+  normal cancel, not an error). A non-interrupted trap or transport closure does
+  throw. Re-confirms the Phase-0 spike through the real `apiListen()` path.
+- **CONFIRMED — deletion frames carry `.dead=true`.** Removing a pre-seeded
+  address over REST while listening emits a minimal `{ ".id", ".dead":"true" }`
+  `!re` (re-confirms `.dead=true`, not the docs' `=.dead=yes`).
+- **Stream shape:** each `!re` → one NDJSON envelope frame
+  (`meta.operation.stream.kind="frame"`, string values, `.dead` preserved); the
+  stream ends with a summary envelope (`stream.kind="summary"`,
+  `data.stopReason` ∈ `count-reached`/`duration-elapsed`/`interrupted`/
+  `transport-error`, plus `frames`/`durationMs`). The CLI exit code keys on
+  whether the stream *started* cleanly, not on per-frame `ok`.