@tikoci/centrs 0.1.4 → 0.1.7

package/commands/api/README.md

@@ -99,19 +99,51 @@ vs `--query` distinction.
 
 ## Validation
 
-Default on. Because the input is a structured path (not a CLI string), the gate is
-`/console/inspect` — **not** `:put [:parse]`:
+Default on. Because the input is a structured path (not a CLI string), the device
+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`.
+- **Designed, not implemented:** value-level advice via `request=completion`
+  (+`input=`) feeding `tips`/`warnings`. Whatever implements it must not fall
+  back to `request=completion` at a *command* path (`path=` ending at the verb):
+  that shape hangs REST and closes native API on RouterOS 7.12.2, and no centrs
+  code uses it. Completion at an *argument* path (`print,proplist`, as `retrieve`
+  does) answers normally on the same build. See the 7.12.2 finding in
+  `AGENTS.md` (GH#343).
 - **Carve-out:** a script-shaped `POST /rest/execute` is a CLI string, not a path,
-  so 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).
+  so structured inspect is `not-applicable` (`meta.validation.semantic`). It
+  follows the CLI-string pipeline instead: offline analysis, then live
+  `:put [:parse ...]`, then run. An offline rejection is still a byte span with
+  no connection; an offline pass or abstention continues to the device stage.
+  `meta.validation.stages[]` reports both decisions. A missing or blank `script`
+  is still `input/invalid-command`, not a syntax rejection. Validation passing
+  is not the run succeeding: `as-string` makes the console's own text the reply
+  body, so a runtime rejection arrives as an HTTP-200 `ret`. `/execute` output
+  is normalized through the same grounded result table `execute` uses, so
+  `no such item` fails the envelope with a `routeros/*` code while the stages
+  stay `passed`. Ordinary output that merely contains a fault string is
+  unaffected — the result matchers are anchored, not substring.
+- Structured path requests are **not** offline-gated. The input is a path plus a
+  body, not a CLI string, and an offline *path* gate collides with GH#211's
+  unlisted-path decision. On the success path `meta.validation.stages[]` is
+  absent there; on a `validation/*` rejection it is present and reports the
+  offline stage `skipped` with that reason, so the breakdown never implies an
+  analysis that did not run.
+
+`--validate=false` skips **both** stages of the preflight — one flag, one meaning
+(constitution: validation); RouterOS still re-validates writes server-side.
+Disabling validation to make a call pass is forbidden (constitution: validation
+is the product).
+
+`--raw` **defaults** `--validate` to false — it does not override it (GH#154).
+The resolution order is the explicit `--validate` flag, then `--raw`, then
+`CENTRS_VALIDATE` / the CDB comment-kv / config, then the `true` default. So
+`--raw` alone behaves as it always has and behaves the same on every machine
+whatever the environment holds, while `--raw --validate=true` runs the gate and
+reports a rejection in the `--raw` error shape (`{code,message}` on stderr,
+nonzero exit, no `data` key) — which is how you debug `api` when centrs itself is
+the suspect.
 
 ## Write confirmation
 
@@ -157,7 +189,15 @@ RouterOS produces multi-frame output two ways, and `api` treats them differently
   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` →
+  bound it; Ctrl-C stops and still emits the summary. The `--duration` window
+  starts once validation is done, so it excludes validation (and the connect and
+  login validation needs). With `--no-validate`, connect and login happen inside
+  the window. Stopping on `--duration` or Ctrl-C sends RouterOS `/cancel`, and
+  centrs waits up to `--timeout` for the router to acknowledge it. A router that
+  never does gets its session closed locally, and the summary carries a
+  `transport/cancel-unacknowledged` warning (#385). Reaching `--count` sends
+  `/cancel` best-effort and closes the session without waiting, so it never
+  carries that warning (examples L5). `--via rest-api --stream` →
   `transport/capability-unsupported`. The exit code reflects whether the stream
   *started* cleanly, not whether every frame was `ok`.
 

package/commands/api/examples.md

@@ -155,7 +155,49 @@ centrs api $R execute -X POST -f script=':put [/system/identity/get name]' --use
 ```
 
 Envelope: `ok: true`, `data` is string-shaped and contains the CHR identity;
-`meta.validation.semantic=not-applicable` (script, not a path).
+`meta.validation.semantic=not-applicable` (script, not a path) and
+`meta.validation.stages` is `offline: passed` then live `device: passed` from
+`:put [:parse ...]`.
+
+### 16b. The `/execute` script is gated offline (GH#354)
+
+Until GH#354 the script-mode carve-out meant this surface ran **no** preflight at
+all. The offline analyzer is the whole stage-1 gate here, and it opens no
+connection — the unreachable port proves it.
+
+```bash
+centrs api 127.0.0.1:1 execute -X POST -f script=':put [' --username $U --password $P --yes
+```
+
+Envelope: `ok: false`, `error.code=validation/syntax`,
+`error.context.validationStage="offline"`, `error.context.surface="api /execute"`,
+`error.context.span={"start":5,"end":6}`, and **not** a `transport/*` code.
+`meta.validation.stages` is `offline: failed` then `device: skipped`.
+
+### 16c. Offline pass continues to live `:parse`
+
+```bash
+centrs api $R execute -X POST -f script='/ip/address/add no-such-arg=x' --username $U --password $P --yes
+```
+
+Envelope: `ok: false` with a device validation code
+(`validation/unknown-attribute`, or `validation/syntax` on older RouterOS), and
+`meta.validation.stages` is `offline: passed` then `device: failed`. Offline
+acceptance remains `runtimeAcceptance: not-proven`; it never suppresses the live
+stage.
+
+### 16d. A runtime rejection in `/execute` output is not `ok: true`
+
+```bash
+centrs api $R execute -X POST -f script='/ip/service/set www-ssl certificate=nope' --username $U --password $P --yes
+```
+
+Envelope: `ok: false`, `error.code=routeros/invalid-value`. `as-string` makes
+the console's own text the reply body, so RouterOS carries this rejection in an
+HTTP-200 `ret`; the validation gate stays `passed` because it did pass — the
+command was rejected at run, not at validation. Ordinary output that merely
+mentions a fault string (`:put "status: no such item appears in help"`) stays
+`ok: true`.
 
 ### 17. `--via rest-api --listen` is rejected
 
@@ -209,6 +251,20 @@ proplist). Combining an id with `--query`/`--proplist` folds the id into the RES
 matching the native `?.id=` read. (Plain id-only reads still use the `GET …/$ID`
 URL form; see example 5's re-read.)
 
+### 22. `--raw --validate=true` still runs the gate (#154)
+
+```bash
+centrs api $R ip/no-such-menu --raw --validate=true --username $U --password $P
+```
+
+`--raw` only **defaults** `--validate` to false, so an explicit `--validate=true`
+wins and the `/console/inspect` preflight runs. The rejection comes back in the
+`--raw` error shape, not the envelope: stdout empty, stderr a compact
+`{"code":"validation/unknown-path","message":…}`, nonzero exit, and no `data`
+key. Contrast example 13, where bare `--raw` skips the preflight entirely. This
+pair is how you tell a RouterOS rejection from a centrs bug while staying on the
+bare-passthrough surface.
+
 ## native-api (`--via native-api`)
 
 The same contract over the binary API. Validation still runs through
@@ -278,7 +334,28 @@ stdout is the bare rest-style array (string values); exit code 0.
 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.
+Envelope: `ok: true`, `data` contains the CHR identity and validation reports
+offline plus live `:parse` stages passed.
+
+### N8b. Native `/execute` also rejects at live `:parse`
+
+```bash
+centrs api $A execute -X POST -f script='/ip/address/add no-such-arg=x' --via native-api --port $API_PORT --username $U --password $P --yes
+```
+
+Envelope: `ok: false`; the accepted version-specific validation code is
+`validation/unknown-attribute` or `validation/syntax`, with stages
+`offline: passed`, `device: failed`.
+
+### N8c. Native `/execute` runtime rejection fails the envelope
+
+```bash
+centrs api $A execute -X POST -f script='/ip/service/set www-ssl certificate=nope' --via native-api --port $API_PORT --username $U --password $P --yes
+```
+
+Envelope: `ok: false`, `error.code=routeros/invalid-value`, with the validation
+stages still `passed` — the same normalization as REST, since both adapters
+surface the `as-string` console text as `data`.
 
 ## listen / `--stream` (native-api only)
 
@@ -326,6 +403,27 @@ centrs api $A ip/address --stream --duration 2s --via native-api --port $API_POR
 With no change during the window, the stream ends after ~2 s with a summary
 envelope whose `data.stopReason=duration-elapsed`. Exit code 0.
 
+### L5. A router that ignores `/cancel` cannot hold the process open
+
+```bash
+centrs api $A ip/address --stream --duration 200ms --timeout 1s --via native-api --port $API_PORT --username $U --password $P
+```
+
+A stream stopped by `--duration` or Ctrl-C sends `/cancel` and waits up to
+`--timeout` for the router's acknowledgement (the interrupted `!trap` and
+`!done`). If none arrives, centrs closes the session itself. The summary still
+reports its stop reason (`duration-elapsed` or `interrupted`), exit code is 0,
+and `warnings` carries `transport/cancel-unacknowledged`. A router that answers
+inside the window gets no warning. `--count` sends `/cancel` without waiting,
+so it exits at once and never warns (#385).
+
+RouterOS on CHR always acknowledges `/cancel`, so this example runs against a
+loopback native-API peer that ignores it, as a real CLI process:
+`test/integration/api-stream-cancel.test.ts` covers `--duration`, SIGINT,
+`--count` and the cooperative control. The session-level cases (silent peer,
+chatty peer, trap without `!done`, close after cancel) are in
+`test/unit/native-api.test.ts`.
+
 ## fanout (multi-target, F…)
 
 These run against a CDB fixture with two records sharing group `$G`: record 0 is

package/commands/devices/README.md

@@ -332,6 +332,7 @@ runs produce stable diffs.
 ## Subcommands
 
 ```text
+centrs devices init                     # create an empty CDB at the resolved path
 centrs devices list [--group G] [--where attr=value]
                     [--near lat,lon,radius] [--bbox south,west,north,east]
                     [--format json|yaml|text]
@@ -361,8 +362,16 @@ clack-style prompt used by `@tikoci/quickchr`); it is **not** a separate
 field-editing verb, and invoking it today returns `usage/not-implemented`. There
 is no `update`.
 
+- `init` creates an empty open CDB at the resolved path (`--cdb-file`,
+  `CENTRS_CDB_FILE`, or the default), with parent directories and mode `0600`.
+  It never overwrites: on an existing, readable CDB it succeeds with a
+  `cdb/file-exists` warning and writes nothing. An explicit path is created only
+  by `init`; every other subcommand reports `cdb/not-found` for it (typo
+  protection), and that error names `init`.
 - `list` (alias `print`) shows resolved targets, their record type, group, and
-  a one-line provenance summary. No network IO. `--where attr=value`
+  a one-line provenance summary. Each row carries the `identity=`/`mac=`/`ip=`
+  lookup keys it resolves by (when set), so one call maps names to records. No
+  network IO. `--where attr=value`
   (repeatable, AND-combined) filters by CDB-stored facts/comment-kv plus core
   record fields (`target`/`group`/`identity`/`mac`) — e.g. `--where
   lat=37.7749`. `--near lat,lon,radius` and `--bbox south,west,north,east`

package/commands/devices/examples.md

@@ -29,7 +29,8 @@ centrs devices list --cdb-file $CDB
 ```
 
 Envelope: `ok: true`, `data` is an array of `{ target, recordType, group?,
-user, sources }`. No `meta.timing.request`.
+user, identity?, mac?, ip?, sources }` — the lookup keys appear only when the
+record's comment sets them. No `meta.timing.request`.
 
 ### 2. List a single group
 
@@ -46,7 +47,8 @@ valid success.
 centrs devices list --cdb-file /tmp/does-not-exist.cdb
 ```
 
-Errors with `cdb/not-found`. `details_url` populated.
+Errors with `cdb/not-found`. `details_url` populated. The remediation names
+`centrs devices init --cdb-file <path>` (example 54).
 
 ## show
 
@@ -634,3 +636,32 @@ Both succeed: the `add` stores the freeform comment verbatim, and the later
 `set timeout=5000` does **not** raise `input/incomplete-gps` even though the
 record's GPS pair is incomplete. Touching `lat`/`lon` (e.g. `set lat=…`) would
 re-enable the pairing check.
+
+## init
+
+`init` is the explicit way to start a CDB at a path you choose (#376). Reads
+and mutations never create an explicit `--cdb-file`/`CENTRS_CDB_FILE`; only the
+default path is created implicitly on first run.
+
+### 54. Start a repo-local CDB
+
+```bash
+centrs devices init --cdb-file ./lab/winbox.cdb --json
+centrs devices add 192.0.2.1 --user robot-reader --cdb-file ./lab/winbox.cdb --json
+```
+
+Creates missing parent directories and an empty open CDB with mode `0600`.
+`data` is `{ cdbFile, created: true, recordCount: 0 }`. The `add` then succeeds.
+
+### 55. `init` never clobbers
+
+```bash
+centrs devices init --cdb-file ./lab/winbox.cdb --json
+```
+
+On an existing, readable CDB: `ok: true`, `data.created: false`,
+`data.recordCount` is the current count, and a `cdb/file-exists` warning says
+nothing was written. As with `git init`, re-running is safe. An existing file that
+does not load fails with that load error (`cdb/parse-failed`,
+`cdb/password-required`) and is left untouched. A location that cannot be
+written fails with `cdb/create-failed`.

package/commands/execute/README.md

@@ -1,7 +1,7 @@
 # execute
 
 Run a RouterOS CLI command and return its (semi-structured) output. `execute`
-is the single read/write surface for RouterOS add/set/remove and other
+is the single read/write surface for RouterOS configuration and operational
 CLI-shaped commands — there is no separate `update` command.
 
 Status: `rest-api`, `native-api`, `mac-telnet`, and `ssh` are `CHR-passed` (see
@@ -15,21 +15,45 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
 
 - Mirror RouterOS `execute` semantics. Input is a CLI string; output is
   console-shaped text (or structured records for path+verb writes) wrapped in
-  the standard envelope. This includes write-shaped add/set/remove.
-- Validation is two-stage (see constitution: validation; grounded on CHR 7.23.3,
+  the standard envelope. This includes selector-, positional-id-, and
+  non-CRUD-shaped writes.
+- Validation runs **offline first, then on the device** (see constitution:
+  validation; GH#354). Stage 1 is the corpus-gated analyzer over the exact
+  command string, with no connection: a syntax fault is rejected with a byte
+  span in `error.context.span` and the adapter is never dialed, and
+  `meta.validation.stages[]` then shows the device stage `skipped`. Stage 1
+  cannot see an unknown attribute — it has no per-menu schema — so stage 2 is
+  not optional.
+- Stage 2 is itself two gates (grounded on CHR 7.23.3,
   GH#230): a single `:put [:parse "<cmd>"]` covers both the syntax and the
   unknown-attribute (name-level) gate on **every** transport — `:parse` never
   throws; its return value's printed form (`(evl …)` / `(evl bad parameter …)` /
-  `(<%% bad command name …)`) is read from the REST/native `ret` *and* the
-  console output. That check is necessary, not sufficient: value-type errors pass
-  it, and the `/console/inspect` / server re-validation semantic checks are
-  separate.
+  `(<%% bad command name …)`, or a bare line-anchored `syntax error` /
+  `expected …` / `missing … (line N column M)`, examples V4) is read from the
+  REST/native `ret` *and* the console output. An accepted return can echo
+  those words, so only the anchored forms reject. That check is necessary, not sufficient: value-type errors pass
+  it, and the `/console/inspect request=child` / server re-validation semantic
+  checks are separate. Command-level `request=completion` is deliberately not
+  used: it hangs REST and closes native API on RouterOS 7.12.2 (GH#343), while
+  `child` returns the complete argument-name set immediately.
   The outer RouterOS string literal escapes backslash, quote, and dollar so
   validation parses the caller's exact command rather than expanding variables
   in the wrapper.
-- centrs owns the **script-vs-structured gate** (`canonicalizeExecuteCommand` +
-  `isWriteShaped` in `src/execute.ts`): it decides which validation runs and
-  whether the write-confirm prompt fires. The shared `rosetta`/`lsp-routeros-ts`
+- centrs owns the **script-vs-structured gate** (`canonicalizeExecuteCommand` in
+  `src/execute.ts`): it decides which validation and transport path runs.
+  `isWriteShaped` is deliberately independent: script fallback for `[find]`, a
+  positional id, or other non-`key=value` input never bypasses confirmation.
+  Known read verbs are allowlisted; an unknown menu verb fails closed as a
+  write-shaped operation. In script mode every command head in a statement
+  (the statement start and each `[…]` or `{…}` body) must be a read: its verb
+  is the first word past the known menu prefix, so `/ip address print` is a
+  read and `/user expire-password print` is not (examples W3). Root mutators such as `/import` and indirect
+  execution through `:execute` are write-shaped too, and so is any command
+  carrying `file=`: RouterOS redirects command output into a device file, so
+  `/ip/address/export file=address` creates `address.rsc` and
+  `/file/print file=test` creates `test.txt` even though `export` and `print`
+  are read verbs. The shared
+  `rosetta`/`lsp-routeros-ts`
   canonicalizer is for canonicalization only — never the structured predicate
   (widening `structured` is a product regression). Pinned by
   `test/unit/execute-canonicalize-contract.test.ts`; the parser-vendoring
@@ -59,12 +83,11 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
   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).
+- **Run-time fault mapping.** A successful transport can still carry a RouterOS
+  rejection in `/execute`'s `ret`. Result detection lives beside the grounded
+  mappings in `src/core/routeros-errors.ts`, uses anchored result shapes so
+  ordinary output containing error-like prose remains output, and preserves a
+  passed validation history while failing the overall envelope.
 - 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
@@ -73,13 +96,33 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
   terminal width, so each transport handles width differently. **mac-telnet** is
   the only one that negotiates a size: `src/protocols/mac-telnet-console.ts`
   answers the device's terminal-size probe with a deliberately tall/wide screen,
-  so captured columns are neither wrapped nor paginated. **SSH execute** runs
-  *without* a pseudo-tty (`src/protocols/ssh.ts`), so RouterOS emits no
-  terminal-wrapped output to begin with — there is nothing to negotiate.
-  **REST/native-api** are not consoles, so terminal width never applies (they
-  return structured records, or a string `ret` for script-mode). There is
-  therefore no per-call `--width` knob today — an explicit width override is
-  deferred until a concrete need appears.
+  so captured columns are neither paginated nor wrapped *at the negotiated
+  width*. **SSH execute** runs *without* a pseudo-tty (`src/protocols/ssh.ts`),
+  so no width is negotiated at all. **REST/native-api** are not consoles, so a
+  terminal width never applies (they return structured records, or a string
+  `ret` for script-mode). There is therefore no per-call `--width` knob today —
+  an explicit width override is deferred until a concrete need appears.
+- **A device-side wrap that no width negotiation reaches (GH#352).** Declaring a
+  width is not sufficient, because RouterOS can wrap for reasons that are not
+  about width. On 7.23.6 / 7.24.3 / 7.25beta4 a settings menu with exactly one
+  property prints its value **one character per line**: `/system/identity/print`
+  returns `name: C` / `H` / `R` where 7.24.2 returns `name: CHR`. Measured on
+  stock CHR, the wrap is identical over REST `POST /rest/execute`, over
+  `ssh user@host "<cmd>"`, and over the mac-telnet console — including the
+  mac-telnet reader that has already answered the size probe with 512 columns,
+  and the ssh client that negotiates nothing. The console login modifiers
+  (`+c512w200h`, `+ct`, `+e`) do not change it, and it is not proportional to
+  the value's length. Every multi-property `print` is unaffected on the same
+  build, as is `:put [/system/identity/get name]`.
+
+  Consequence for this command: `data.ret` carries the device's console text
+  **verbatim**, wrap included — centrs cannot tell a layout newline from
+  content, and inventing a de-wrapper would corrupt legitimate output. Callers
+  that need a value rather than a rendering should read it structurally
+  (`retrieve`, or `api`) or ask the device for the scalar
+  (`:put [<menu>/get <property>]`). The integration examples compare identities
+  with `print` column wrapping collapsed for this reason — see
+  `collapsePrintWrapping` in `test/integration/chr.ts`.
 - Attribute values pass through **verbatim** — centrs does not guess types or
   coerce them (RouterOS REST tolerates string values; the native API is
   all-strings). Unlike `jo`-style KV builders, there is no per-value
@@ -187,8 +230,8 @@ many tokens):
   it fans out; mixing it with positionals or CDB selectors is
   `usage/conflicting-flags` (constitution: resolution providers).
 
-Because `execute` is the primary **write** path, a write-shaped fan-out
-(add/set/remove) is gated by **`--yes`**, confirmed **once** up front; without it
+Because `execute` is the primary **write** path, a write-shaped fan-out is gated
+by **`--yes`**, confirmed **once** up front; without it
 the error names the blast radius (how many routers). Write-ness is determined from
 the command alone (`canonicalizeExecuteCommand` + `isWriteShaped`), so the gate
 fires before any target is dialed. Per-target validation still runs because

package/commands/execute/examples.md

@@ -73,7 +73,7 @@ arbitrary script expressions. The `$a` variable must survive the validation
 wrapper: if that outer string expands it before `:parse`, this example fails even
 though RouterOS accepts the original command.
 
-### 5. Syntax reject from `:put [:parse ...]`
+### 5. Syntax reject before the write round-trip
 
 Malformed CLI is rejected by the syntax gate before semantic validation or the
 write round-trip.
@@ -82,9 +82,16 @@ write round-trip.
 centrs execute $R '/ip/address/add address="unterminated interface=ether1' --via rest-api --username $U --password $P --yes
 ```
 
-Envelope: `ok: false`, `error.code=validation/syntax`, `error.cause` preserves
-the RouterOS parse error string from `:put [:parse ...]`, `meta.via=rest-api`,
-and no address is added.
+Envelope: `ok: false`, `error.code=validation/syntax`, `meta.via=rest-api`, and
+no address is added.
+
+**Which stage rejects it changed in GH#354.** This input is now caught by the
+*offline* stage, so `error.context.validationStage="offline"`,
+`error.cause="explain/canonicalizer/unterminated-string"`,
+`error.context.span={"start":24,"end":54}`, and the device is never contacted —
+see V1–V3 below. It reached `:put [:parse ...]` before that. The code, the
+`meta.via`, and the no-mutation guarantee are unchanged, which is why the
+assertion in `test/integration/execute.test.ts` still reads `validation/syntax`.
 
 ### 6. Semantic reject that `:parse` accepts
 
@@ -202,14 +209,16 @@ centrs execute $A "/ip/address/remove numbers=$ID" --via native-api --port $API_
 Envelope: `ok: true`, `meta.via=native-api`. A subsequent retrieve of
 `/ip/address` does not contain `$ID`.
 
-### 15. Native syntax reject from `:parse`
+### 15. Native syntax reject
 
 ```bash
 centrs execute $A '/ip/address/add address="unterminated interface=ether1' --via native-api --port $API_PORT --username $U --password $P --yes
 ```
 
-Envelope: `ok: false`, `error.code=validation/syntax`, `error.cause` preserves
-the RouterOS parse error string, `meta.via=native-api`, and no address is added.
+Envelope: `ok: false`, `error.code=validation/syntax`, `meta.via=native-api`, and
+no address is added. The native twin of example 5, and it moved the same way:
+the offline stage rejects this input now, so the verdict no longer depends on
+the transport at all.
 
 ### 16. Native semantic reject after clean parse
 
@@ -285,6 +294,10 @@ Envelope: `ok: true`, `meta.via=mac-telnet`, `data.ret` is the console output an
 contains the device identity (cross-checked against REST). `meta.validation.source`
 is `:put [:parse ...] over mac-telnet`.
 
+RouterOS 7.23.6/7.24.3/7.25beta4 print a one-property menu's value one
+character per line (GH#352), so the comparison collapses `print` column
+wrapping on both sides rather than asserting the device's layout.
+
 ### 21. Write (add) over mac-telnet
 
 ```bash
@@ -329,6 +342,10 @@ Envelope: `ok: true`, `meta.via=ssh`, `data.ret` is the cleaned console output a
 contains the device identity (cross-checked against REST). `meta.validation.source`
 is `:put [:parse ...] over ssh`.
 
+RouterOS 7.23.6/7.24.3/7.25beta4 print a one-property menu's value one
+character per line (GH#352), so the comparison collapses `print` column
+wrapping on both sides rather than asserting the device's layout.
+
 ### S2. Multi-line read returns cleaned, column-aligned output
 
 ```bash
@@ -356,6 +373,150 @@ centrs execute 127.0.0.1 '/ip/address/add address=198.51.100.51/32 interface=eth
 Envelope: `ok: false`, `error.code=validation/unknown-attribute`, `meta.via=ssh`,
 and no address is added — the console `:parse` gate catches `bogus` pre-mutation.
 
+## Offline gate (stage 1)
+
+Validation runs offline before it runs on the device
+([`docs/CONSTITUTION.md` → Validation is the product](../../docs/CONSTITUTION.md#validation-is-the-product),
+GH#354). These two prove the stage exists and that a stage-1 rejection reaches no
+router. Run by `test/integration/execute.test.ts`.
+
+### V1. Offline reject, with the device stage never asked
+
+`:put [` is an unclosed bracket. The old local quote preflight counted quotes
+only, so this used to cost a full round trip to be told no; the analyzer rejects
+it with a byte span before anything is dialed.
+
+```bash
+centrs execute $R ':put [' --via rest-api --username $U --password $P --json
+```
+
+Envelope: `ok: false`, `error.code=validation/syntax`,
+`error.context.validationStage="offline"`,
+`error.context.span={"start":5,"end":6}`,
+`error.context.diagnostics[0].code="explain/canonicalizer/unclosed"`,
+`error.position` absent (the offline byte offset is never dressed up as a
+RouterOS-reported one), `meta.validation.source` is the offline analyzer, and
+`meta.validation.stages` is `offline: failed` followed by `device: skipped`.
+
+### V2. The same rejection with no reachable router at all
+
+The proof that stage 1 opens no connection: point the same command at a port
+nothing is listening on. A gate that dialed first would report a
+`transport/*` error or hang until the timeout.
+
+```bash
+centrs execute 127.0.0.1:1 ':put [' --via rest-api --username $U --password $P --json
+```
+
+Envelope: identical to V1 — `ok: false`, `error.code=validation/syntax`,
+`error.context.validationStage="offline"` — and **not** a `transport/*` code.
+
+### V3. `--validate=false` disables the offline stage too
+
+One flag, one meaning. The escape hatch has to reach stage 1, or a caller hitting
+an analyzer defect would have no way past it. RouterOS then rejects the command
+itself on the run.
+
+```bash
+centrs execute $R ':put [' --via rest-api --username $U --password $P --json --validate=false
+```
+
+Envelope: `ok: false`, `error.code=routeros/request-failed` with RouterOS's own
+`syntax error (line 1 column 7)` in the summary — the **device** rejecting it, not
+centrs — plus `meta.validation.enabled=false`, `meta.validation.result="skipped"`,
+and `meta.validation.stages` listing **both** stages as `skipped`. A gated
+surface always reports every stage, so a consumer reading `stages` never has to
+special-case the disabled shape.
+
+### V4. A device-only `missing …` rejection is still a rejection
+
+The offline stage passes `/ip/address/find where=`: an empty `where` is not a
+structural fault it can see. RouterOS's `:parse` returns
+`missing value for where (line 1 column 24)` (CHR 7.24.4), a bare diagnostic
+like `syntax error`, so the device stage must reject it (GH#375). Before that
+fix the classifier only knew `syntax error`, `bad command name` and
+`expected …`, so it reported this reply as a pass and the command ran.
+
+```bash
+centrs execute $R '/ip/address/find where=' --via rest-api --username $U --password $P --json
+```
+
+Envelope: `ok: false`, `error.code=validation/syntax`, `error.context.detail`
+is RouterOS's own `missing value for where (line 1 column 24)`,
+`error.position={"line":1,"column":24}`, and `meta.validation.stages` is
+`offline: passed` followed by `device: failed`.
+
+CHR 7.24.4 controls, via `:put [:parse "…"]`: `find where` without `=` parses
+(IL). `print where=` is rejected differently (`expected end of command`, at
+`where`). An unclosed bare `{` block or menu block (`/ip address {` then
+newlines) returns `missing closing brace (line 3 column 1)`, while an unclosed
+`do={` returns `expected closing brace`. Offline analysis usually catches the
+unclosed-brace cases first.
+
+## Write authorization and returned runtime faults
+
+These regressions are transport-independent and run in
+`test/integration/execute.test.ts` (with MCP's selector form also covered by
+`test/integration/mcp.test.ts`).
+
+### W1. Script-mode selector and positional writes still require confirmation
+
+```bash
+centrs execute $R '/ip/address/remove [find comment=centrs-write-gate]' --via rest-api --username $U --password $P </dev/null
+```
+
+The same contract holds for `/ip/address/remove *1`. Both stay script-mode so
+RouterOS receives the raw selector/id syntax, but the independent safety gate
+returns `usage/confirmation-required` before validation or mutation.
+
+### W2. Non-CRUD mutation verbs still require confirmation
+
+```bash
+centrs execute $R '/ip/address/disable numbers=*1' --via rest-api --username $U --password $P </dev/null
+```
+
+Envelope: `ok: false`, `error.code=usage/confirmation-required`; the address
+remains enabled. Unknown RouterOS menu verbs also fail closed as write-shaped.
+Root mutators such as `/import` and indirect execution through `:execute` use
+the same gate.
+
+### W3. Space-separated menu reads run without confirmation
+
+```bash
+centrs execute $R '/system identity print' --via rest-api --username $U --password $P </dev/null
+```
+
+Envelope: `ok: true`. The space-separated spelling puts menu segments and the
+verb in bare words, so the gate walks the known menu prefix and reads the first
+word past it as the verb. `/ip address print where …` and
+`:put [/system identity get name]` are reads the same way. The walk is also what
+keeps an unlearned command gated: `/user expire-password print` names
+`expire-password`, a published command outside both verb allowlists, whose
+argument happens to be `print`, so it returns `usage/confirmation-required`.
+Every command head in a statement is checked, including `[…]` and `do={…}`
+bodies.
+
+### R1. A post-validation `/execute` rejection fails the overall envelope
+
+```bash
+centrs execute $R '/ip/service/set www-ssl certificate=nope' --via rest-api --username $U --password $P --yes --json
+```
+
+Envelope: `ok: false`, `error.code=routeros/invalid-value`, exit `1`, while
+`meta.validation.result="passed"` and both stages remain `passed`: the rejection
+happened at run time, after the scoped checks completed. The same result is
+asserted over native API.
+
+### R2. Error-like prose remains ordinary script output
+
+```bash
+centrs execute $R ':put "status: no such item appears in ordinary output"' --via rest-api --username $U --password $P --json
+```
+
+Envelope: `ok: true`. Returned-text classification uses anchored grounded
+shapes; it does not fail arbitrary output merely because it contains an error
+phrase.
+
 ## Target selection (fan-out)
 
 These exercise the shared target-selection grammar