@tikoci/centrs 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -8,6 +8,52 @@ documenting cross-cutting shifts that affect contributors and consumers.
 
 ## Unreleased
 
+## 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 +260,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
@@ -146,6 +153,7 @@ quickchr
 RAML
 readcdb
 remotehub
+retarget
 restraml
 romon
 ros
@@ -418,3 +426,11 @@ 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

package/README.md

@@ -32,8 +32,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). |

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`.

package/commands/api/README.md

@@ -0,0 +1,159 @@
+# api
+
+A structured RouterOS **API passthrough**, modeled on `gh api`. You give it a
+REST-style endpoint path and an HTTP method; centrs fills in credentials from the
+CDB / env / flags, validates the request through `/console/inspect`, runs the
+single REST or native-API operation, and returns the result in the standard
+envelope.
+
+Status: `CHR-passed` over `rest-api` and `native-api` (single-target),
+including open-ended `--stream` follow (native-api only), per `docs/MATRIX.md`;
+multi-target fan-out is a later phase. This file describes intent and flags; the
+matrix holds the cell states. Load-bearing rules — envelope, errors, settings
+precedence, identity, validation, protocol selection — live in
+[`docs/CONSTITUTION.md`](../../docs/CONSTITUTION.md); the `(constitution: …)`
+notes below point there rather than restating them.
+
+`api` absorbs the former `stream` command: open-ended follow is `api <router>
+<endpoint> --stream` (or the `/listen` endpoint form). `--listen` is an accepted
+alias of `--stream`.
+
+## Where `api` sits — the verb trichotomy
+
+centrs has three RouterOS-touching verbs; pick by shape of work, not by habit:
+
+- **`execute`** — the CLI-like runner. The full RouterOS console surface
+  (multi-command / script blocks, console-text output, `:put [:parse]` gate). Most
+  powerful and lowest-level, but the caller authors a RouterOS CLI string and the
+  output is console text.
+- **`retrieve`** — read-only data extraction. Discoverable, structured-out,
+  always read.
+- **`api`** (this command) — the structured middle. Enforces the
+  *one-command-per-operation* semantics of the REST / native API (no code
+  blocks), **can write**, and forces structured input **and** output. For an AI
+  agent this is usually the friendliest write path: no CLI-string authoring,
+  structured in/out. It does **not** replace `execute` — console-only and
+  multi-command work still needs `execute`.
+
+## Synopsis
+
+```text
+centrs api <router> <endpoint> [flags]
+```
+
+- `<router>` — IP, DNS, MAC, or CDB-resolved identity (constitution: identity).
+- `<endpoint>` — a REST-style path, leniently normalized. All of
+  `ip/address`, `/ip/address`, `rest/ip/address`, `/rest/ip/address`,
+  `"ip address"`, `'ip address'` canonicalize to `/ip/address`. A trailing id
+  segment (`ip/address/*1`) addresses one row. A trailing `/listen` segment
+  infers `--stream` + `--via native-api`.
+
+The HTTP method (`-X`, default `GET`) is honored **literally** against RouterOS's
+REST mapping — `GET`→print/get, **`PUT`→add**, `PATCH`→set, `DELETE`→remove,
+`POST`→run-any-command. Note the trap: **`PUT` is RouterOS's create**, not
+`POST`. centrs never rewrites your method, but warns (`tip/rest-verb-mapping`)
+when a bare-collection `POST` carries create-looking fields.
+
+## Flags
+
+| Flag | Behavior |
+| ---- | -------- |
+| `-X` / `--method <verb>` | HTTP method, default `GET`, case-insensitive. |
+| `-f <key=value>` | String field, repeatable; assembled into the JSON body. Values pass through verbatim (no type-guessing). |
+| `-d` / `--data <json>` | Raw JSON request body. Collides with `-f` → `usage/conflicting-flags`. |
+| `--input <file\|->` | Read the raw JSON body from a file or stdin (`-`). |
+| `--query` / `--filter <expr>` | RouterOS-side row filter, AND-combined, repeatable. `name=value` (eq), `name!=value` (ne), `name>value`/`name<value` (cmp), `name` (has-property). Maps to REST `.query` words / native `?` words. |
+| `--raw-query <word>` | Verbatim RouterOS query word (repeatable) for OR / absence / stack expressions — e.g. `--raw-query type=ether --raw-query type=vlan --raw-query '#\|'` (OR). Emitted as-is; the caller owns the stack. |
+| `--attribute` / `--proplist <a,b>` | Property projection → `.proplist`. |
+| `--raw` | Strip the envelope; emit bare RouterOS JSON. Implies `--validate=false`; does **not** imply `--yes`. |
+| `--yes` | Confirm a mutating (non-read) request in non-interactive runs. |
+| `--stream` (alias `--listen`) | Native-api-only open-ended follow → NDJSON stream of envelopes, ending with a summary envelope. Inferred from a `/listen` endpoint. `--via rest-api --stream` errors `transport/capability-unsupported` (REST's 60 s cap cannot follow). |
+| `--duration <dur>` / `--count <n>` | Bound a `--stream`: stop after a wall-clock window / after N frames. |
+| `--validate[=false]` | Default `true`. Gate is `/console/inspect` (see Validation). |
+| `--via <protocol>` | `rest-api` (default) or `native-api`. No silent downgrade. |
+| `--format <json\|yaml\|text>` | Output format. Defaults to `json` for `api` (machine-first); `CENTRS_FORMAT` overrides. Under `--stream`, `json`/`yaml` emit one compact envelope per line (NDJSON); `text` emits a concise row per frame. |
+| target/auth | `--host`, `--port`, `--username`/`--user`/`-u`, `--password`, `--insecure`, `--timeout`, `--cdb-file`, `--cdb-password`, `--resolve <none\|arp>` — same single-target resolver as `retrieve`/`execute`. |
+
+Multi-target fan-out (`--group` / `--where` / `--all` / `--default` /
+`--concurrency`, reusing `src/core/fanout.ts`) lands in a later phase. When it
+does, `--stream` is single-session: N>1 targets → `usage/fanout-not-supported`.
+
+## Validation
+
+Default on. Because the input is a structured path (not a CLI string), the gate is
+`/console/inspect` — **not** `:put [:parse]`:
+
+- Path existence + per-verb attribute validity via `request=child`
+  (`validation/unknown-path`, `validation/unknown-attribute`).
+- Value-level advice via `request=completion` (+`input=`) feeding `tips`/`warnings`.
+- **Carve-out:** a script-shaped `POST /rest/execute` is a CLI string, not a path,
+  so the inspect gate is `not-applicable` (`meta.validation.semantic`); RouterOS
+  re-validates on the run.
+
+`--validate=false` (and `--raw`, which implies it) skip the preflight; RouterOS
+still re-validates writes server-side. Disabling validation to make a call pass is
+forbidden (constitution: validation is the product).
+
+## Write confirmation
+
+Read-only **iff** the method is `GET`, or the endpoint terminal verb is
+`print`/`get`, or it is `listen`. Everything else is treated as a write and needs
+confirmation (`--yes` non-interactively, or a TTY prompt) → otherwise
+`usage/confirmation-required`. Two consequences:
+
+- A `POST …/print` paged read does **not** prompt (keyed on the verb, not the
+  wire HTTP method).
+- Streaming does **not** imply read-only: an async-but-mutating command like
+  `/system/license/renew --stream` still confirms.
+
+`--raw` does not bypass this gate.
+
+## Output
+
+Always rest-style JSON in the standard envelope (constitution: result envelope).
+Over native-api the records are re-mapped to the same rest-style shape, with string
+values (the binary API carries no JSON scalar types).
+
+`--raw` is the bare-passthrough escape hatch (the envelope-lossless rule is waived
+for it): success prints only the RouterOS body on stdout; a RouterOS error prints
+the RouterOS error payload to stderr with a nonzero exit; a centrs-side failure
+with no RouterOS response prints a compact `{code,message}` to stderr. Exit code is
+`0` iff `ok`.
+
+## Multi-frame results: bounded vs open-ended
+
+RouterOS produces multi-frame output two ways, and `api` treats them differently:
+
+- **Bounded `duration=` / `monitor` commands are ordinary `api` calls.** Both
+  transports return the accumulated frames as a normal **array** (REST regularizes
+  the native `!re` frames into `.section`-keyed records; native's reader collects
+  them until the command completes). No flag needed — e.g.
+  `centrs api $R interface/monitor-traffic -f interface=ether1 -f duration=5s`
+  returns a `.section` array. REST bounds these at the **60 s** cap (a longer
+  `duration=` terminates early with an error); native has no cap. This is **not**
+  NDJSON.
+- **Open-ended follow is `--stream` (alias `--listen`), native-api only.** Only
+  the native API `/listen` command follows indefinitely (REST cannot — the 60 s
+  cap). Each `!re` becomes one rest-style envelope frame (one NDJSON line; a
+  deletion's `.dead=true` flag is preserved); the stream ends with a summary
+  envelope (`data.stopReason` ∈ `count-reached`/`duration-elapsed`/`interrupted`/
+  `transport-error`, plus `frames` and `durationMs`). `--duration`/`--count`
+  bound it; Ctrl-C stops and still emits the summary. `--via rest-api --stream` →
+  `transport/capability-unsupported`. The exit code reflects whether the stream
+  *started* cleanly, not whether every frame was `ok`.
+
+## MCP (deferred — forward guidance)
+
+`api` is **not** exposed over the MCP frontend yet: the MCP server is the
+least-mature surface, and a raw passthrough sits awkwardly against its "scoped
+verbs, never one tool per RouterOS command" model. But precisely because `api` is
+structured and agent-friendly, it is the strongest *future* MCP candidate for an
+agent driving RouterOS — to be revisited behind the per-device `mcp=ro|rw` +
+`confirm:true` write gate (method-aware: read verbs `ro`, everything else `rw`) and
+the CDB-as-allowlist authorization model (constitution: MCP surface).
+
+## Definition of done
+
+`CHR-passed` only when every example in `examples.md` runs green against a real CHR
+through `bun run test:integration`. See
+[`docs/CONSTITUTION.md`](../../docs/CONSTITUTION.md) for the full done rule.