@tikoci/centrs 0.1.1 → 0.1.2

package/commands/api/examples.md

@@ -0,0 +1,325 @@
+# api — examples
+
+Each numbered example is an executable spec, asserted by CHR integration tests
+(booted by `@tikoci/quickchr`): `test/integration/api.test.ts` (rest-api
+examples), `test/integration/api-native.test.ts` (native-api examples, N…), and
+`test/integration/api-listen.test.ts` (streaming examples, L…), with example N ↔
+assertion N. If a line here is not exercised by a test, the test file is wrong; if
+a line passes only with `--validate=false`, the implementation is wrong (see
+[`docs/CONSTITUTION.md`](../../docs/CONSTITUTION.md)).
+
+`$R` is `<host>:<rest-port>` resolved by quickchr. `$A` is `<host>` and
+`$API_PORT` is the native API port (`chr.ports.api`). `$U` / `$P` are CHR
+credentials provided by the harness. `$ID` is the `.id` returned by the preceding
+add in the same transport section. All write-shaped examples pass `--yes`.
+
+## rest-api (`--via rest-api`, the default)
+
+### 1. GET a list
+
+```bash
+centrs api $R ip/address --username $U --password $P
+```
+
+Envelope: `ok: true`, `data` is an array of rest-style records,
+`meta.via=rest-api`, `meta.validation.source` includes `/console/inspect request=child`.
+
+### 2. Endpoint normalization variants resolve to one path
+
+```bash
+centrs api $R "/rest/ip/address" --username $U --password $P
+centrs api $R "rest/ip/address" --username $U --password $P
+centrs api $R "ip address" --username $U --password $P
+```
+
+Each resolves to the same canonical path; `meta.request.path == "/ip/address"`
+and the `data` array matches example 1.
+
+### 3. GET a singleton
+
+```bash
+centrs api $R system/resource --username $U --password $P
+```
+
+Envelope: `ok: true`, `data` is a single object (not an array) with `uptime`,
+`version`, etc.
+
+### 4. PUT add (RouterOS create; documents the PUT≠POST trap)
+
+```bash
+centrs api $R ip/address -X PUT -f address=198.51.100.10/32 -f interface=ether1 -f comment=centrs-api-rest --username $U --password $P --yes
+```
+
+Envelope: `ok: true`, `data[".id"]` matches `/^\*[0-9A-F]+$/`, `meta.via=rest-api`.
+A subsequent GET of `/ip/address` contains the new row.
+
+### 5. PATCH set by id-in-path
+
+```bash
+centrs api $R ip/address/$ID -X PATCH -f comment=centrs-api-rest-set --username $U --password $P --yes
+```
+
+Envelope: `ok: true`; re-reading `ip/address/$ID` shows the new comment.
+
+### 6. DELETE remove by id-in-path
+
+```bash
+centrs api $R ip/address/$ID -X DELETE --username $U --password $P --yes
+```
+
+Envelope: `ok: true`; a subsequent GET of `/ip/address` does not contain `$ID`.
+
+### 7. Raw JSON body with `-d`
+
+```bash
+centrs api $R ip/address -X PUT -d '{"address":"198.51.100.11/32","interface":"ether1"}' --username $U --password $P --yes
+```
+
+Envelope: `ok: true`, `data[".id"]` present.
+
+### 8. Body from stdin with `--input -`
+
+```bash
+echo '{"address":"198.51.100.12/32","interface":"ether1"}' | centrs api $R ip/address -X PUT --input - --username $U --password $P --yes
+```
+
+Envelope: `ok: true`, `data[".id"]` present.
+
+### 9. Server-side filter with `--query`
+
+```bash
+centrs api $R interface --query type=ether --username $U --password $P
+```
+
+Envelope: `ok: true`, every returned record has `type=ether`; the request carried
+a REST `.query` (not client-side filtering).
+
+### 10. Projection with `--proplist`
+
+```bash
+centrs api $R ip/address --proplist address,interface --username $U --password $P
+```
+
+Envelope: `ok: true`, each record has only the requested properties (plus `.id`).
+
+### 11. Validation rejects an unknown attribute before the write
+
+```bash
+centrs api $R ip/address -X PUT -f address=198.51.100.13/32 -f interface=ether1 -f no-such-arg=x --username $U --password $P --yes
+```
+
+Envelope: `ok: false`, `error.code=validation/unknown-attribute`,
+`meta.validation.source=/console/inspect`, and no address is added.
+
+### 12. Validation rejects an unknown path
+
+```bash
+centrs api $R ip/no-such-menu --username $U --password $P
+```
+
+Envelope: `ok: false`, `error.code=validation/unknown-path`, no request issued.
+
+### 13. `--raw` success prints the bare RouterOS body
+
+```bash
+centrs api $R ip/address --raw --username $U --password $P
+```
+
+stdout is the bare RouterOS JSON array (no `meta`/`warnings`); validation is
+skipped; exit code 0.
+
+### 14. `--raw` RouterOS error → stderr + nonzero exit
+
+```bash
+centrs api $R ip/address -X PUT -f address=not-an-ip -f interface=ether1 --raw --username $U --password $P --yes
+```
+
+stdout is empty; stderr carries the RouterOS error payload as JSON; exit code is
+nonzero.
+
+### 15. Mutating + non-TTY + no `--yes` is refused
+
+```bash
+centrs api $R ip/address -X PUT -f address=198.51.100.14/32 -f interface=ether1 --username $U --password $P </dev/null
+```
+
+Envelope: `ok: false`, `error.code=usage/confirmation-required`, no request
+issued, no address added. (Holds under `--raw` too.)
+
+### 16. POST run a console command via `/rest/execute`
+
+```bash
+centrs api $R execute -X POST -f script=':put [/system/identity/get name]' --username $U --password $P --yes
+```
+
+Envelope: `ok: true`, `data` is string-shaped and contains the CHR identity;
+`meta.validation.semantic=not-applicable` (script, not a path).
+
+### 17. `--via rest-api --listen` is rejected
+
+```bash
+centrs api $R ip/address --listen --via rest-api --username $U --password $P
+```
+
+Envelope: `ok: false`, `error.code=transport/capability-unsupported` (REST cannot
+follow); no silent open-ended poll.
+
+### 18. `--query` not-equal maps to a negated stack word
+
+```bash
+centrs api $R interface --query type!=ether --username $U --password $P
+```
+
+Envelope: `ok: true`, no returned record has `type=ether`; the request carried
+REST `.query` words `["type=ether","#!"]` (eq then NOT-top).
+
+### 19. `--raw-query` expresses OR
+
+```bash
+centrs api $R interface --raw-query type=ether --raw-query type=loopback --raw-query '#|' --username $U --password $P
+```
+
+Envelope: `ok: true`, returns the union of `ether` and `loopback` interfaces; the
+raw words are passed through verbatim as `.query` (REST) / `?` words (native).
+
+### 20. Bounded `duration=` command returns a `.section` array (not a stream)
+
+```bash
+centrs api $R interface/monitor-traffic -X POST -f interface=ether1 -f duration=5s --username $U --password $P --yes
+```
+
+Envelope: `ok: true`, `data` is an **array** of `.section`-keyed records (one per
+~second), `meta.via=rest-api`. This is an ordinary bounded call — no `--listen`,
+no NDJSON. `monitor-traffic` is a command (not `print`/`get`), so it is a
+`POST` and write-classed (needs `--yes`); centrs never relaxes that to read-only.
+(REST bounds it at the 60 s cap; native has no cap.)
+
+### 21. GET one row by id together with `--proplist`
+
+```bash
+centrs api $R ip/address/$ID --proplist address --username $U --password $P
+```
+
+Envelope: `ok: true`, `data` is a **single object** (not an array) carrying only
+the projected property `address` (RouterOS omits `.id` unless it is in the
+proplist). Combining an id with `--query`/`--proplist` folds the id into the REST
+`.query` (`.id=$ID`) and rides a `POST …/print`, then unwraps the one row —
+matching the native `?.id=` read. (Plain id-only reads still use the `GET …/$ID`
+URL form; see example 5's re-read.)
+
+## native-api (`--via native-api`)
+
+The same contract over the binary API. Validation still runs through
+`/console/inspect`, issued as native commands. Values are strings.
+
+### N1. GET a list
+
+```bash
+centrs api $A interface -X GET --via native-api --port $API_PORT --username $U --password $P
+```
+
+Envelope: `ok: true`, `data` is an array of rest-style records (string values),
+`meta.via=native-api`.
+
+### N2. PUT add (returns `.id`)
+
+```bash
+centrs api $A ip/address -X PUT -f address=198.51.100.20/32 -f interface=ether1 --via native-api --port $API_PORT --username $U --password $P --yes
+```
+
+Envelope: `ok: true`, `data[".id"]` present.
+
+### N3. PATCH set by id (id → `=.id=` word)
+
+```bash
+centrs api $A ip/address/$ID -X PATCH -f comment=centrs-api-native-set --via native-api --port $API_PORT --username $U --password $P --yes
+```
+
+Envelope: `ok: true`; re-reading shows the new comment.
+
+### N4. DELETE remove by id (id → `=.id=` word)
+
+```bash
+centrs api $A ip/address/$ID -X DELETE --via native-api --port $API_PORT --username $U --password $P --yes
+```
+
+Envelope: `ok: true`; the row is gone.
+
+### N5. GET one by id (→ `print ?.id=`)
+
+```bash
+centrs api $A ip/address/$ID2 -X GET --via native-api --port $API_PORT --username $U --password $P
+```
+
+Envelope: `ok: true`, `data` is a single object whose `.id` is `$ID2`.
+
+### N6. Validation rejects an unknown attribute over native
+
+```bash
+centrs api $A ip/address -X PUT -f address=198.51.100.21/32 -f interface=ether1 -f no-such-arg=x --via native-api --port $API_PORT --username $U --password $P --yes
+```
+
+Envelope: `ok: false`, `error.code=validation/unknown-attribute`, no row added —
+caught by the inspect gate, not a native `!trap`.
+
+### N7. `--raw` over native
+
+```bash
+centrs api $A interface --raw --via native-api --port $API_PORT --username $U --password $P
+```
+
+stdout is the bare rest-style array (string values); exit code 0.
+
+### N8. POST run a console command via native `/execute`
+
+```bash
+centrs api $A execute -X POST -f script=':put [/system/identity/get name]' --via native-api --port $API_PORT --username $U --password $P --yes
+```
+
+Envelope: `ok: true`, `data` contains the CHR identity.
+
+## listen / `--stream` (native-api only)
+
+Open-ended follow. `--stream` is the primary flag; `--listen` is an accepted
+alias and a trailing `/listen` endpoint segment infers it. Output is NDJSON: one
+envelope per change frame, then a terminating summary envelope.
+
+### L1. `--stream` streams a change as an NDJSON frame, then a summary
+
+```bash
+centrs api $A ip/address --stream --count 1 --via native-api --port $API_PORT --username $U --password $P
+```
+
+While listening, the harness adds an address over REST. stdout is NDJSON: at least
+one envelope frame for the new row (`meta.operation.stream.kind=frame`), then a
+final summary envelope (`meta.operation.stream.kind=summary`,
+`data.stopReason=count-reached`, `data.frames>=1`). Exit code 0 (stream started
+cleanly).
+
+### L2. A deletion frame carries `.dead`
+
+```bash
+centrs api $A ip/address --stream --duration 3s --via native-api --port $API_PORT --username $U --password $P
+```
+
+The harness removes a pre-seeded address; an emitted frame's record carries
+`.dead=true` (a minimal `{ ".id", ".dead" }` record, per the CHR-grounded
+`commands/api/AGENTS.md`).
+
+### L3. `/listen` endpoint infers native + streaming
+
+```bash
+centrs api $A "ip/address/listen" --count 1 --port $API_PORT --username $U --password $P
+```
+
+No `--stream` / `--via` given; the `/listen` endpoint infers `--stream` and
+`--via native-api` (`meta.via=native-api`). Same NDJSON shape as L1.
+
+### L4. Bounded `--duration` reports its stop reason
+
+```bash
+centrs api $A ip/address --stream --duration 2s --via native-api --port $API_PORT --username $U --password $P
+```
+
+With no change during the window, the stream ends after ~2 s with a summary
+envelope whose `data.stopReason=duration-elapsed`. Exit code 0.

package/commands/btest/README.md

@@ -17,7 +17,10 @@ on the centrs **server**; `test/integration/btest-client.test.ts` runs the centr
 **client** against a real RouterOS `/tool/bandwidth-server` over a host→guest
 `tcp:2000` forward — unauthenticated TCP receive, an **EC-SRP5 client proof
 verified by RouterOS's own verifier**, and a wrong-password reject. TCP
-multi-connection (`connection-count > 1`) data fan-out is a follow-up. See
+multi-connection (`connection-count > 1`) data fan-out is implemented for
+unauthenticated tests (the client joins the negotiated extra connections; the join
+format is grounded against RouterOS 7.23.1); authenticated sessions stay
+single-stream. See
 `docs/MATRIX.md` ("Peer measurement (`btest`)") for the cell states — that is the
 only status surface. v1 scope: **both** modes (client + server), **EC-SRP5 +
 unauthenticated** auth, **TCP and UDP** tests. Legacy pre-6.43 double-MD5 is out of
@@ -85,7 +88,7 @@ centrs btest server [--authenticate[=false]] [--user U] [--password P] \
 | `--direction <receive\|transmit\|both>` | `direction`, default `receive` | `receive` = download (server→client), `transmit` = upload. |
 | `--duration <dur>` | `duration` | Bounds the run; reuses `parseDuration`. Omit for open-ended (Ctrl-C). |
 | `--interval <dur>` | `interval`, default `1s` | Report cadence (`20ms`..`5s`). One report frame per interval. |
-| `--connection-count <n>` | `connection-count` (1..255) | **TCP only.** Parallel TCP data connections. |
+| `--connection-count <n>` | `connection-count` (1..255) | **TCP only.** Parallel TCP data connections. centrs opens the negotiated extra connections (join format grounded against RouterOS 7.23.1) so throughput aggregates across streams. **Authenticated (EC-SRP5) sessions stay single-stream** — the post-auth token is not captured — and emit a `routeros/btest-connection-count-single-stream` warning. |
 | `--local-udp-tx-size <n>` | `local-udp-tx-size` (28..64000) | **UDP only.** Client→server packet size. |
 | `--remote-udp-tx-size <n>` | `remote-udp-tx-size` (28..64000) | **UDP only.** Server→client packet size. |
 | `--local-tx-speed <bps>` | `local-tx-speed` | Cap on client→server rate (bits/sec). |
@@ -120,10 +123,20 @@ test, data then flows on the server's allocated UDP ports
 from sequence gaps. For a TCP test, the bulk data rides `connection-count` TCP
 connections and goodput is measured on the data stream (TCP/IP headers excluded,
 matching RouterOS accounting). For multi-connection TCP the server's OK response
-carries a 2-byte **session token**; the extra connections reconnect and present
-that token to join the same test (no re-auth). Throughput and CPU are exchanged
+carries a 2-byte **session token**; the client opens `connection-count − 1`
+additional connections, each presenting a 16-byte join `[token:u16 BE][0x02][0 …]`
+(grounded against RouterOS 7.23.1, direction-independent) to join the same test
+without re-auth, and drives them into the shared counters so throughput aggregates.
+Throughput and CPU are exchanged
 once per `interval` as a 12-byte **status message** on the TCP channel
-(`[0x07][0x80|cpu][00 00][seq u32 LE][bytesReceived u32 LE]`).
+(`[0x07][0x80|cpu][00 00][seq u32 LE][bytesReceived u32 LE]`). The receiver of a
+transmit (server for `transmit`, both peers for `both`) sends this so the
+transmitter paces from the peer's `bytesReceived`. For `direction=both` the
+status frames are **interleaved into the bulk data stream** (no length framing),
+so the client demuxes them out of its receive loop by their structural marker —
+without that feedback the client's TX saturates the link and starves
+server→client RX. RouterOS clears the CPU high bit the centrs client sets, so the
+marker matches on the two reserved zero bytes, not the high bit.
 
 ### Authentication (EC-SRP5)
 
@@ -141,7 +154,7 @@ will not offer EC-SRP5 against an `authenticate=yes` server) maps to
 
 btest runs over time, so it emits **live records** during the run plus a final
 **summary**. v1 keeps the formats simple and **defers a broader JSON-streaming
-decision** — it does *not* adopt the `stream` command's NDJSON-stream-of-envelopes
+decision** — it does *not* adopt `api --stream`'s NDJSON-stream-of-envelopes
 contract yet (see Open questions):
 
 - **`text`** (default) — human-readable live reports during the run
@@ -214,10 +227,11 @@ Decided with the user. Both cells have direct gated `CHR-passed` evidence:
   maps onto the guest bandwidth server on 2000 (the same SLIRP inbound path that
   already carries REST/SSH — no firewall change). The centrs client dials
   `127.0.0.1:<host port>` and proves **TCP receive**, unauth and **EC-SRP5** (its
-  client proof verified by RouterOS's real server verifier), plus a wrong-password
-  reject. **TCP only** — UDP would need the server's datagrams to traverse SLIRP
-  back to the host, which this forward does not provide, so UDP client→server stays
-  loopback/transitive.
+  client proof verified by RouterOS's real server verifier), a wrong-password
+  reject, **TCP multi-connection fan-out** (`connection-count=4`), and **UDP
+  receive/both**. The UDP server→client return needs no UDP forward: it rides the
+  guest→host SLIRP gateway (`10.0.2.2:clientUdpPort`, the same path the server cell
+  uses), which works because the client socket is left unconnected (#86, #88).
 
 The fast/deterministic backstop under both is **centrs client ↔ centrs server
 loopback** (`127.0.0.1`, injected sockets) covering the full client↔server matrix,
@@ -226,32 +240,43 @@ EC-SRP5 both roles, and the option-grammar rejects.
 while implementing the EC-SRP5 framing and the server-side verifier; it is **not**
 an integration test (it cannot run in CI) and **not** part of the long-term plan.
 
-**Honest grounding caveat:** both cells are now directly CHR-passed. The remaining
-transitive-only paths are **UDP client→CHR-server** (the SLIRP reverse-NAT path the
-TCP forward does not cover) and TCP **multi-connection** fan-out — both deferred,
-not yet gated.
+**Honest grounding caveat:** both cells are now directly CHR-passed, **including
+TCP multi-connection fan-out** — `test/integration/btest-client.test.ts` gates a
+centrs client opening `connection-count=4` against a real RouterOS
+`/tool/bandwidth-server`; RouterOS accepts all 3 secondary joins and data flows on
+every connection (`activeConnections: 4`). The *throughput increase* multiple
+streams give is a WAN/latency property and is not observable over the near-zero-
+latency SLIRP loopback, so the gate asserts the fan-out, not a higher number (the
+per-connection drive is asserted deterministically by the loopback unit test).
+**UDP client receive/both is now CHR-gated too** — the server→client return rides
+the guest→host SLIRP gateway, no UDP forward needed (#88). The remaining fan-out
+edge is **authenticated** multi-connection (capturing the EC-SRP5 post-auth token),
+still single-stream.
 
 ## Open questions
 
-- **JSON streaming is deliberately deferred.** btest does not adopt the `stream`
-  command's NDJSON-stream-of-envelopes contract yet; v1 streams `text` / `csv` and
-  returns a single summary envelope for `json` / `yaml`. Revisit a streaming-JSON
-  shape — ideally shared with `stream` — once that contract is settled.
-- **UDP receive/both through SLIRP is unproven.** Before the integration suite
-  relies on server→guest UDP, a **one-shot CHR smoke test** must confirm the path
-  works — i.e. that the RouterOS client originates an initial UDP/NAT probe that
-  opens the SLIRP reverse mapping. Until then the gated UDP coverage is
-  **transmit** (guest→host); TCP already covers both directions.
-- **UDP client→CHR-server and TCP multi-connection are not yet gated.** The direct
-  client→CHR-server gate (`test/integration/btest-client.test.ts`) is **TCP only**;
-  a UDP variant needs the server's datagrams to traverse SLIRP back to the host
-  (the reverse-NAT path), and `connection-count > 1` needs the parallel-stream
-  fan-out. Both remain loopback/transitive until gated. `btest.exe` (wine) is the
-  coding-time grounding peer, not CI.
+- **JSON streaming is deliberately deferred.** btest does not adopt
+  `api --stream`'s NDJSON-stream-of-envelopes contract yet; v1 streams `text` /
+  `csv` and returns a single summary envelope for `json` / `yaml`. Revisit a
+  streaming-JSON shape — ideally shared with `api --stream` — once it has settled.
+- **UDP client receive/both is gated (#88).** The client cell
+  (`test/integration/btest-client.test.ts`) lands real UDP server→client throughput:
+  the return rides the guest→host SLIRP gateway (`10.0.2.2:clientUdpPort`), needing
+  no UDP forward and no quickchr change — it works because the client socket is left
+  unconnected (#86).
+- **Only the server-cell host→guest UDP direction stays unproven.** The server cell
+  gates UDP *transmit* (guest→host, which SLIRP NATs cleanly); the reverse (centrs
+  server → CHR client, host→guest) would need a UDP hostfwd for the data ports, so it
+  is not yet asserted. `btest.exe` (wine) is the coding-time grounding peer, not CI.
+- **Authenticated multi-connection stays single-stream.** Fan-out negotiates the
+  session token from the unauthenticated OK; capturing the EC-SRP5 post-auth token
+  to fan out authenticated tests is a follow-up (#103). centrs warns
+  (`routeros/btest-connection-count-single-stream`) when the realized connection
+  count falls short of the request. The **server-side** secondary-accept is its own
+  follow-up (#100).
 
 ## Out of scope (v1)
 
-Legacy pre-6.43 double-MD5 auth; a UDP client→CHR-server gated test (TCP is gated;
-UDP needs SLIRP reverse-NAT); the ≥3-router "test-through" topology RouterOS
+Legacy pre-6.43 double-MD5 auth; the ≥3-router "test-through" topology RouterOS
 recommends for measuring a *transit* device (centrs is an endpoint peer); TUI/proxy
 btest frontends (later, over the stable core).

package/commands/btest/examples.md

@@ -15,17 +15,19 @@ matrix's honest grounding split (`docs/MATRIX.md`, "Peer measurement (`btest`)")
   loss / direction against the CHR's own `/tool/bandwidth-test` status output
   (CHR 7.23.1, `bun run test:integration`). Examples **4** (wrong-credentials) and
   **5** (multi-connection TCP) are **designed but not yet gated** — the auth-reject
-  path is covered by the loopback unit test, and the multi-stream fan-out is a
-  documented follow-up — so they are not part of the asserted run.
+  path is covered by the loopback unit test, and example 5 is the **server-side**
+  secondary-accept (distinct from the now-gated **client** fan-out in example 11),
+  still a documented follow-up — so they are not part of the asserted run.
 - **Gated `CHR-passed` (client cell): centrs client → CHR bandwidth-server** —
   examples **6** (TCP receive) and **8** (EC-SRP5 client role + wrong-password
   reject) are *also* asserted directly against a real RouterOS
   `/tool/bandwidth-server`, over a host→guest `tcp:2000` forward
   (`test/integration/btest-client.test.ts`, CHR 7.23.1). This is what makes the
   **client** cell `CHR-passed`: centrs's EC-SRP5 **client proof** is verified by
-  RouterOS's own server verifier. TCP only — the EC-SRP5 example is run over TCP
-  receive here (the loopback variant below uses UDP); UDP client→server stays
-  loopback (README, Open questions).
+  RouterOS's own server verifier. Example **11** (TCP **multi-connection**
+  fan-out), a TCP `direction=both` #85 regression guard, and **UDP receive/both**
+  (#88 — the server→client return over the guest→host SLIRP gateway) are gated in
+  the same suite.
 - **Unit / loopback (client cell + codec)** — examples 6–10. centrs client ↔
   centrs server on `127.0.0.1` with injected sockets; the EC-SRP5 both-roles math
   and the pre-socket option-grammar rejects (`test/unit/btest.test.ts`). These are
@@ -113,12 +115,13 @@ contains a `transport/auth-failed` entry (the EC-SRP5 proof did not verify) and
 `data.sessions` is empty — no session opened, no throughput. The CHR side reports
 an authentication failure.
 
-### 5. Multi-connection TCP transmit
+### 5. Multi-connection TCP transmit (server-side accept)
 
-> *Designed, not yet gated* — the server's parallel-stream fan-out for
-> `connection-count > 1` is not built yet (the session token is negotiated, but
-> secondary TCP joins are not served). Documented follow-up; not part of the
-> asserted run.
+> *Designed, not yet gated* — this is the **server-side** fan-out: centrs's
+> `btest server` accepting parallel secondary joins from a client. The session
+> token is negotiated but centrs's server does not yet serve secondary TCP joins.
+> Distinct from the **client** fan-out (example 11), which **is** implemented and
+> gated. Tracked as a follow-up (#100); not part of the asserted run.
 
 ```bash
 centrs btest server --authenticate=false --bind 0.0.0.0 --duration 20s --format json
@@ -188,3 +191,25 @@ centrs btest client $SRV --protocol udp --local-udp-tx-size 99999
 `ok: false`, `error.code = "validation/option"` (UDP size must be `28..64000`), no
 socket opened. The same gate rejects `connection-count` outside `1..255`,
 `interval` outside `20ms..5s`, and (server) `max-sessions` outside `1..1000`.
+
+## centrs client TCP multi-connection (gated; client cell)
+
+### 11. Multi-connection TCP receive fan-out
+
+```bash
+centrs btest client <router> --protocol tcp --direction receive --connection-count 4 --duration 4s --format json
+```
+
+Against a real RouterOS `/tool/bandwidth-server` (`authenticate=no`), centrs reads
+the session token from the primary's OK and opens the 3 extra TCP data
+connections, each presenting the grounded join `[token:u16 BE][0x02][0 …]`. The
+summary is `ok: true` with `data.activeConnections: 4` and non-zero aggregate
+throughput — real RouterOS accepted all 3 secondary joins and data flowed on every
+connection (the per-connection drive is also asserted deterministically by the
+loopback unit test). The *throughput increase* multiple streams provide is a
+high-latency/WAN-link property and is **not** observable over the near-zero-latency
+SLIRP loopback (a single TCP stream already saturates it), so the gate asserts the
+fan-out itself, not a higher number. Gated in
+`test/integration/btest-client.test.ts` (CHR 7.23.1). An **authenticated**
+`--connection-count > 1` run instead stays single-stream (`activeConnections: 1`)
+and carries a `routeros/btest-connection-count-single-stream` warning.

package/commands/execute/README.md

@@ -52,6 +52,12 @@ Status: `rest-api`, `native-api`, `mac-telnet`, and `ssh` are `CHR-passed` (see
   else passes its `detail`/body plus the HTTP status through
   `mapRouterOsError({ transport: "rest-api", httpStatus })`. There is no longer
   a hand-rolled `routeros/*` table on the REST side.
+- **Run-time fault mapping — later (JG-28).** `mapRouterOsError`'s table covers
+  the faults seen so far; a known gap is errors that *pass* `:parse`/validation
+  but fail at **run time** (a syntactically valid command the router rejects when
+  executed). `tikoci/vscode-tikbook` has an error-string mapping for these worth
+  porting into `src/core/routeros-errors.ts`. Background research, not yet
+  scheduled — captured here so it isn't lost (no GitHub issue by design).
 - Output is *string*-shaped for script-mode; richer parsing is a future
   concern. The envelope must still distinguish RouterOS errors from successful
   runs (a 200 with a RouterOS error string is still an error — see
@@ -195,9 +201,9 @@ Protocol selection: an unresolved MAC target auto-selects mac-telnet (covered by
 ## Open shape questions
 
 - ~~How to expose multi-line / async / progress output~~ — **resolved:**
-  open-ended follow/streaming reads are the separate read-only `stream` verb
-  (NDJSON stream of envelopes; see `commands/stream/README.md`). `execute` stays
-  single-shot read/write; it does not grow a follow mode.
+  open-ended follow/streaming reads are `api … --stream` (NDJSON stream of
+  envelopes; see `commands/api/README.md`). `execute` stays single-shot
+  read/write; it does not grow a follow mode.
 - ~~Whether `--strict` should reject "succeeded with stderr-like content."~~ —
   **decided:** `--strict` promotes any warning on an otherwise-successful run to
   `ok: false` (nonzero exit), like `-Werror`; the default stays lenient

package/commands/retrieve/README.md

@@ -45,7 +45,7 @@ centrs retrieve <router> snmp <oid|MIB name> [flags]
 | `--attributes <a,b,c>`              | Alias for `--attribute` with comma-separated input.                                       |
 | `--all-attributes`                  | Equivalent to RouterOS `details=true`. Mutually exclusive with `--attribute(s)`.          |
 | `--list-attributes` (alias `--list`) | Return the available attribute names for the path. No `print`/`get` is run.              |
-| `--once`                            | Bounded single read of a monitor-style menu (RouterOS `once`): returns **one** envelope and never follows. Open-ended follow is the separate `stream` verb. See constitution: protocol selection. |
+| `--once`                            | Bounded single read of a monitor-style menu (RouterOS `once`): returns **one** envelope and never follows. Open-ended follow is `api … --stream`. See constitution: protocol selection. |
 | `--query <expr>`                    | RouterOS-side **row** filter (maps to `.query`), repeatable; returns matching rows as an **array**. This is how you read one row by name (`--query name=ether1`). **Not Implemented** yet — returns `validation/not-implemented`. |
 | `--filter <expr>`                   | RouterOS row filter; same `.query` mapping and not-implemented handling as `--query`.       |
 | `--where <attr>=<value>`            | Device-class selector: fan out across CDB records whose stored fact/comment-kv matches (e.g. `--where board=RB5009`). Repeatable (AND). Filters *which devices*, not RouterOS rows. See constitution: target selection. |

package/docs/CONSTITUTION.md

@@ -228,8 +228,8 @@ repeats. The union is **de-duped by CDB record index** and run through the same
 per-target pipeline; the `data` array is reassembled in resolved record order,
 not completion order, so repeated runs diff cleanly. Destructive multi-target
 operations (e.g. `devices remove` across a group) require `--force`. `terminal`
-and single-session `stream` are not fan-out surfaces and reject N>1 with
-`usage/fanout-not-supported`.
+and a single-session `api --stream` follow are not fan-out surfaces and reject
+N>1 with `usage/fanout-not-supported`.
 
 `--where` filters *which devices* by CDB-stored facts; keep it distinct from
 `retrieve`/`execute`'s `--query`/`--filter`, which filter *RouterOS rows* in the
@@ -266,7 +266,7 @@ Per-operation preferences, downgrade order in parens:
 | Operation | Preferred | Downgrade order |
 | --------- | --------- | --------------- |
 | retrieve  | rest-api, native-api; snmp for OID/MIB reads (future) | rest-api, native-api |
-| stream    | native-api, ssh | (REST cannot follow — 60s cap; bounded or rejected) |
+| api       | rest-api, native-api; `--stream` follow native-api only | rest-api, native-api (no silent downgrade) |
 | execute   | native-api → rest-api → mac-telnet | native-api, rest-api, mac-telnet, ssh, romon, winbox-terminal |
 | terminal  | ssh | mac-telnet (L2 only when ssh fails or MAC given) |
 | transfer  | size/direction-aware: rest-api/native-api for ≤60 KB writes & all reads (chunked), sftp for large uploads | sftp ⇄ rest/native by size; scp · fetch · ftp explicit-only |
@@ -288,9 +288,9 @@ Rules:
   access needs explicit ARP opt-in.
 - **`measure` (btest) is explicit-only** — never in the auto-select/downgrade
   chain, never a substitute, and no other command rides it.
-- Per-command selection **depth** lives in the command READMEs: `stream`'s
-  follow/NDJSON contract and the REST-cannot-follow constraint
-  (`commands/stream/README.md`), `transfer`'s size/direction-aware method
+- Per-command selection **depth** lives in the command READMEs: `api`'s
+  `--stream` follow/NDJSON contract and the REST-cannot-follow constraint
+  (`commands/api/README.md`), `transfer`'s size/direction-aware method
   selection and the explicit-only `scp`/`ftp`/`fetch`
   (`commands/transfer/README.md`), SNMP's MIB-cache
   (`commands/retrieve/README.md`), and btest's port/auth