@tikoci/centrs 0.1.1 → 0.1.3

package/commands/api/README.md

@@ -0,0 +1,177 @@
+# 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`, including multi-target
+fan-out and open-ended `--stream` follow (native-api only), per
+`docs/MATRIX.md`. 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`. Streaming is single-session — it cannot combine with
+multi-target fan-out (see below).
+
+## 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. |
+| `--group <name>` / `--where <attr>=<value>` / `--near <lat>,<lon>,<radius>` / `--bbox <south>,<west>,<north>,<east>` / `--all` / `--default` / `--concurrency <n>` | Multi-target fan-out (see below). Repeatable `--group`/`--where`; `--near`/`--bbox` select by device GPS (lat-first; see constitution: target selection). The union de-dupes by CDB record index. |
+| target/auth | `--host`, `--port`, `--username`/`--user`/`-u`, `--password`, `--insecure`, `--timeout`, `--cdb-file`, `--cdb-password`, `--resolve <none\|arp>` — same single-target resolver as `retrieve`/`execute`. |
+
+## Fan-out (multi-target)
+
+Selecting more than one router — any selector flag (`--group` / `--where` /
+`--near` / `--bbox` / `--all` / `--default`) or more than one positional target — switches `api` into
+**fan-out mode** (`src/api-fanout.ts`, on the shared `src/core/fanout.ts` engine
+and the `src/resolver/selection.ts` grammar). A plain single-positional call
+stays the single-target envelope. Output is the locked `FanoutData` envelope
+(`data = { summary, targets[] }`; outer `ok` = orchestration success; per-target
+failures are inner `ok:false`), and the process exit code is granular: `0`
+all-ok, `2` partial, `1` orchestration error or every target failed. See
+`docs/CONSTITUTION.md` (Target selection) for the shared grammar and `--where`
+vs `--query` distinction.
+
+- **Writes fan out under `--yes`**, confirmed once up front (not per target).
+  Without `--yes`, the error names the blast radius (how many routers) and that
+  `--yes` is required.
+- **`--listen`/`--stream` is single-session** → `usage/fanout-not-supported` in
+  fan-out mode. **`--raw` strips the envelope** → `usage/conflicting-flags` in
+  fan-out mode (per-target envelopes can't be bare).
+
+## 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.

package/commands/api/examples.md

@@ -0,0 +1,428 @@
+# api — examples
+
+Each numbered example is an executable spec asserted by CHR integration tests
+(booted by `@tikoci/quickchr`), example N ↔ assertion N:
+`test/integration/api.test.ts` (rest-api examples),
+`test/integration/api-native.test.ts` (native-api examples, N…),
+`test/integration/api-listen.test.ts` (streaming examples, L…), and
+`test/integration/api-fanout.test.ts` (fan-out examples, F…). 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.
+
+## fanout (multi-target, F…)
+
+These run against a CDB fixture with two records sharing group `$G`: record 0 is
+the live CHR (comment `board=chr`), record 1 is an unreachable host (comment
+`board=dead`). Fan-out output is the locked `FanoutData` envelope
+(`data = { summary, targets[] }`; outer `ok` = orchestration success; per-target
+failures are inner `ok:false`), with the granular exit code (0 all-ok / 2 partial /
+1 all-failed or orchestration error). See `test/integration/api-fanout.test.ts`.
+The `--raw`/`--listen` + fan-out guards are network-free and validated in
+`test/integration/cli-smoke.test.ts`.
+
+### F1. `--group` fans a GET out; a dead target is an inner failure
+
+```bash
+centrs api --group $G ip/address --cdb-file $CDB --json
+```
+
+`ok: true`, `data.summary = { total: 2, ok: 1, failed: 1 }`, `data.targets[]` in
+record-index order (`[0, 1]`): target 0 is an inner success (`meta.via=rest-api`),
+target 1 is inner `ok:false` with `error.code=transport/connection-refused`.
+`meta.operation.kind=fanout`. Exit code 2.
+
+### F2. `--where` selects only the matching device
+
+```bash
+centrs api --where board=chr ip/address --cdb-file $CDB --json
+```
+
+The device-class selector matches only record 0, so `data.summary = { total: 1,
+ok: 1, failed: 0 }`, one inner success. Exit code 0.
+
+### F3. An empty selection is `ok:true` with summary 0/0/0
+
+```bash
+centrs api --group no-such-group ip/address --cdb-file $CDB --json
+```
+
+`ok: true`, `data.summary = { total: 0, ok: 0, failed: 0 }`, `data.targets = []`,
+and a `cdb/empty-group` warning. Exit code 0.
+
+### F4. A mutating fan-out without `--yes` is rejected, naming the blast radius
+
+```bash
+centrs api -X PUT ip/address -f address=10.99.0.1/32 -f interface=ether1 --group $G --cdb-file $CDB --json
+```
+
+Non-interactive and unconfirmed: outer `ok:false`,
+`error.code=usage/confirmation-required`, and the message names the router count
+(`2 router(s)`) and that `--yes` is required. No write is attempted. Exit code 1.
+
+### F5. A mutating fan-out with `--yes` writes across the selected devices
+
+```bash
+centrs api -X PUT ip/address -f address=10.99.0.7/32 -f interface=ether1 --where board=chr --yes --cdb-file $CDB --json
+```
+
+Confirmed once up front; the add runs on record 0 only (selected by `--where`).
+`data.summary = { total: 1, ok: 1, failed: 0 }`, the inner success carries the
+created `.id`. Exit code 0.
+
+The fixture for F6–F9 adds record 2 — the reserved `__default__` credential record.
+
+### F6. `--all` fans across every record except `__default__`
+
+```bash
+centrs api --all ip/address --cdb-file $CDB --json
+```
+
+`data.summary = { total: 2, ok: 1, failed: 1 }`, `data.targets[]` record indices
+`[0, 1]` (record 2 `__default__` is excluded). Exit code 2.
+
+### F7. A positional + `--group` union de-dupes by record index
+
+```bash
+centrs api $R0 --group $G ip/address --cdb-file $CDB --json
+```
+
+`$R0` is record 0's target, also a member of `$G`; the union is `{0, 1}` — record
+indices `[0, 1]`, `total = 2` (not 3). Exit code 2.
+
+### F8. `--concurrency` bounds the worker pool
+
+```bash
+centrs api --group $G --concurrency 1 ip/address --cdb-file $CDB --json
+```
+
+Runs one target at a time; `meta.operation.concurrency = 1`, still
+`data.summary = { total: 2, ok: 1, failed: 1 }`. (`--concurrency 2abc` / `1.5` are
+rejected at parse time with `usage/invalid-concurrency`.) Exit code 2.
+
+### F9. `--default` selects `__default__`, which fails the connectable guard
+
+```bash
+centrs api --default ip/address --cdb-file $CDB --json
+```
+
+The reserved record is a credential fallback, not a connectable router, so its one
+target fails deterministically: inner `ok:false` with
+`error.code=target/unresolved` (never a `transport/dns` attempt on `"__default__"`).
+`data.summary = { total: 1, ok: 0, failed: 1 }`. Exit code 1 (every target failed).