@tikoci/centrs 0.1.3 → 0.1.6

package/docs/CONSTITUTION.md

@@ -9,15 +9,22 @@ This file is short on purpose. Resist the urge to grow it.
 
 ## What centrs is
 
-A typed library, with CLI/MCP/TUI/proxy frontends, that reaches RouterOS over
-multiple protocols and gives the caller **validated** access plus structured,
-actionable diagnostics. The TypeScript API is the root surface; everything else
-is an adapter over it.
+A typed library for RouterOS analysis and **validated** device access, with
+CLI/MCP/TUI/proxy frontends and structured, actionable diagnostics. The
+TypeScript API is the root surface; everything else is an adapter over it.
+The initial consumers are other TIKOCI tools and developers building integrations.
 
 The product is *not* "REST/SSH/native API wrappers." The product is
 **validation + structured envelopes + identity resolution** on top of those
 transports. Without those, this is a worse `curl`.
 
+`explain` is shared analysis across transports and a useful offline capability
+in its own right. It exposes source structure, facts, uncertainty, and evidence
+without executing the input. Those facts can support future diagnostics in
+other commands' envelopes; that integration is not implemented by declaring
+this boundary. Analysis findings do not grant execution permission or replace
+the runners' validation gates.
+
 centrs also speaks a small set of MikroTik **peer protocols** that are *not*
 RouterOS-command transports — currently the **bandwidth test** (`btest`), which
 mirrors `/tool/bandwidth-test` and `/tool/bandwidth-server`. This is a
@@ -29,29 +36,69 @@ friendly errors, but the "validate a RouterOS-shaped command" gate below does
 
 ## Validation is the product
 
-Every RouterOS-shaped call goes through canonicalize → validate → run →
-re-validate-server-side. Validation is not optional polish.
+Every RouterOS-shaped operation sent to a device goes through canonicalize →
+validate → run → re-validate-server-side. Analysis-only `explain` never runs
+the analyzed input; offline analysis opens no connection. Validation on the
+runners is not optional polish.
+
+The `validate` step itself has **two stages, in this order** (GH#354):
+
+1. **Offline** — the same corpus-gated analyzer `explain` publishes, run over
+   the input with no connection (`src/offline-gate.ts`). A rejection is a byte
+   span and no round trip; the protocol adapter is never dialed. This stage runs
+   on every transport, for `execute` and for `api`'s `/execute` script mode.
+2. **Device** — the RouterOS-side probe below: `:put [:parse "…"]` and/or
+   `/console/inspect request=child`, depending on the command shape and the
+   transport.
+
+The stages are not interchangeable and neither subsumes the other. Offline has
+no per-menu schema (decision 3 — no offline schema snapshot), so it cannot see
+an unknown attribute; the device probe is version-fragile (GH#343), so where it
+is unsafe the offline stage is what keeps the gate from degrading to nothing. A
+clean offline pass is **necessary, never sufficient** — `explain` publishes
+`runtimeAcceptance: "not-proven"` for exactly this reason. An offline `warn` is
+an ABSTENTION and passes through to the device stage; only a `fail` rejects.
+
+`meta.validation.stages[]` reports what each stage concluded, including a stage
+that was skipped and why. A reader must always be able to tell "the device
+accepted it" from "the device was never asked".
+
+`--validate=false` disables **both** stages — one flag, one meaning. A bypass
+that covered only the device stage would leave a caller stranded behind a
+stage-1 defect with no escape at all, and the analyzer is demonstrably wrong in
+both directions today (GH#355 is a live false accept, GH#351 a live false
+reject). That is a reason for the flag to reach both stages, not a license to
+use it: the rule below still holds — a wrong rejection is fixed in the
+validator, with CHR evidence.
 
 - `retrieve` and other read-shaped calls validate against
   `/console/inspect request=syntax path=...,print` (path joined by commas) and
   attribute inspection. The path syntax (commas, no leading slash, last token
   is the verb) is part of the validator contract.
 - `execute` and other CLI-shaped calls validate with `:put [:parse "..."]` plus
-  a semantic gate. **How `:parse` surfaces an error is transport-specific**
-  (grounded on CHR 7.23.1): `:parse` *does* reject an unknown attribute
-  (`bad parameter <name>`) and malformed CLI (`syntax error`), but over REST that
-  text rides the **HTTP-200 `ret` value** (no error status), and over the
-  **native API** `:put [:parse]` returns an opaque `*NN` handle that reveals
-  nothing at all. centrs's REST/native syntax gate runs `:parse` but does not
-  read the `ret`, so for those transports the unknown-attribute catch comes from
-  the separate **`/console/inspect`** semantic gate (or the server's own
-  write re-validation); the `:parse` round-trip there mainly backstops transport
-  errors and the local quote preflight. Over **mac-telnet** the interactive
-  console *prints* the `:parse` result, so centrs reads it and a single console
-  `:parse` covers both syntax and the unknown-attribute (semantic) gate — no
-  `/console/inspect` table needed. In every case a clean parse is necessary, not
-  sufficient on its own; semantic validation is a distinct, transport-appropriate
-  step (`/console/inspect`, the console `:parse` text, or server re-validation).
+  a semantic gate. Grounded on CHR 7.23.3 (GH#230), **`:parse` never throws** —
+  it returns a script value whose printed form carries the verdict. For a bare
+  menu path a clean parse prints `(evl /canonical/path)` with abbreviations
+  expanded; for script-shaped input (e.g. `:put …`, `:global …`, `where …`) the
+  accepted return echoes the script body and may contain arbitrary text such as
+  `expected`. Rejection forms are `(evl bad parameter <name> (line N column M)
+  /path)`, `(<%% bad command name <name> (line N column M) …)`, and the
+  line-anchored `expected … (line N column M)` (spellings: `expected end of
+  command`, `expected command name`, `expected input value`) / `syntax error
+  (line N column M)`. That text rides the **HTTP-200 `ret` value** (REST,
+  `as-string`), the native `as-string` `ret`, and the console's printed output
+  alike — so a single `:put [:parse ...]` covers both the syntax and the
+  **unknown-attribute** gate on every transport. centrs sends `as-string` and now
+  reads the `ret`/printed value (the previous gate ignored it, so it rejected
+  nothing). Because the accepted return echoes the body, the matcher must anchor
+  on the diagnostic shape (the `(<%%` wrapper, or a trailing `(line N column M)`)
+  and never on a bare English word — `expected` is also a real
+  `/ip/firewall/connection` field name.
+  That unknown-attribute check is **name-level only**: `:parse` does not validate
+  parameter *values* (`/ip/address/add address=not-an-ip` parses clean). So a
+  clean parse is necessary, not sufficient, and value-type plus the remaining
+  semantic validation stay distinct steps — `/console/inspect` or the server's
+  own re-validation on the write round-trip.
 - **Peer-measurement commands (`btest`) are exempt from this gate** — they issue
   no RouterOS command, so they validate *option-grammar* + the **EC-SRP5** auth
   exchange instead (the envelope, identity-resolution, and friendly-error
@@ -260,6 +307,43 @@ falls in `--near`'s radius **or** `--bbox`.
 by a distinct `--new-group` flag on `devices add`/`set`, so record selection and
 field-setting never collide on one flag.
 
+#### Resolution providers
+
+Target resolution has **two independent axes**, and centrs keeps them separate so
+the resolver is generalized **once**, not per source (the umbrella plan is #174):
+
+- **Axis A — selection** ("which devices"): the target-selection grammar above.
+- **Axis B — connection-fact origin** ("where host/port/auth for a member come
+  from"): what a resolved member yields. Today: a **CDB record** or an ad-hoc
+  **literal** (+ the `__default__` ladder). Tomorrow: a live descriptor or an
+  inventory entry.
+
+Sources fall into two kinds, and the distinction is normative:
+
+- **Selector-source** — participates in the Axis-A grammar. **CDB** (now), and
+  **TikTOML** next (#137). Multiple selector-sources union into one selection;
+  the split-brain precedence between them is #137's problem, not resolved here.
+- **Named-live-provider** — addressed *only* by an explicit named flag, **never**
+  matched by a selector; fanned out by repeating the flag. Because it owns an
+  **ephemeral** endpoint it also **bypasses** the settings/`__default__` ladder and
+  **conflicts** with `--host`/`--port`/`--username`/`--password`/`--ssh-key`. These
+  are properties of *live/ephemeral* providers, not of any one provider. **quickchr**
+  (`--quickchr <name>`, #134) is the first. A named-live-provider selection is
+  **exclusive** (v1): mixing it with `<router>` positionals or selector flags is
+  `usage/conflicting-flags` — one flag stays single-target, repeating it fans
+  out. Relaxing exclusivity later is additive.
+
+Connection facts resolve into one neutral **per-service endpoint map**
+(`src/resolver/service-endpoint.ts`: `via → ServiceEndpoint`, each carrying
+availability, host, port, TLS, auth, and provenance). A **selector-source** is the
+*degenerate single-endpoint* case — one record materialized lazily once `--via` is
+known. A **named-live-provider** populates the map directly, since it genuinely
+exposes different facts per transport. Providers must **not** be flattened to a
+single host/port: that shape is the contract quickchr's descriptor and TikTOML's
+`services` block both map onto, and flattening it forces exactly the re-plumb #174
+exists to prevent. A `--via` whose service key a provider does not supply is a
+typed unsupported-provider error, never a silent fallback.
+
 ### MCP surface: the CDB is the allowlist
 
 The MCP frontend (`commands/mcp/`) is an adapter over this core, not a new set of
@@ -352,22 +436,38 @@ default), so key auth is the normal sftp path.
 
 ## Done definition
 
-A feature is done when its **CHR integration test is green** against a real
-RouterOS CHR booted by `@tikoci/quickchr`. Not when code exists. Not when unit
-tests pass. Not when the spec says so. This is the **normative** done
-definition; `AGENTS.md` and
+Done requires executable evidence for the capability being claimed. Device
+operations and live analysis require **green CHR integration tests** against a
+real RouterOS CHR booted by `@tikoci/quickchr`, via `bun run test:integration`.
+Code existing or unit tests passing cannot establish live behavior. This is
+the **normative** done definition; `AGENTS.md` and
 `.github/instructions/done-definition.instructions.md` point here (the latter
 carries the Copilot-workflow procedure for satisfying it).
 
-`docs/MATRIX.md` is the single source of truth for *what* is done and defines the
-cell states (`not-started` / `designed` / `coded` / `CHR-passed`). A cell
-advances only with the matching evidence in the same change, and the commit that
-advances it must include the test name and CHR version.
+Offline analysis is `verified` when its applicable command examples and
+contract checks pass without a router, its RouterOS semantic claims have
+committed CHR-grounded evidence, and the command's baseline acceptance criteria
+are satisfied. New or changed RouterOS semantics still require live grounding
+with accepted and rejected controls plus a reproducible capture/replay path;
+offline tests do not establish new device facts. Changes to shared execution
+or transport behavior still require `bun run test:integration`. The offline
+call itself never needs a router merely to satisfy a workflow label.
+
+`docs/MATRIX.md` owns capability status and the selected work track. A
+capability's acceptance criteria — like `explain`'s Offline baseline
+acceptance — live in its `commands/<name>/README.md`; GitHub issues own the
+tasks and dependencies that satisfy those criteria, not the criteria
+themselves. Umbrella issues index that work rather than replacing capability
+status. Status advances only with matching evidence in the same change.
+Record test names, fixture provenance, and CHR versions where applicable.
+Offline verification never advances a live protocol cell to `CHR-passed`.
 
 ## Boundaries
 
 centrs does:
 
+- Analyze RouterOS source independently of a connection, preserving ordered
+  structure, source locations, evidence, and ambiguous/unknown readings.
 - Resolve devices/groups from explicit input, env, CDB, MNDP cache.
 - Choose protocols per the table above and configure them.
 - Validate before execute; re-validate server-side immediately before run.
@@ -380,7 +480,9 @@ centrs does:
 
 centrs does not:
 
-- Replace RouterOS syntax with high-level abstractions.
+- Replace RouterOS syntax with high-level configuration helpers. Normalized
+  representations that preserve its semantics are in scope; reconstructing
+  final device state or predicting network behavior is not an offline parse claim.
 - Treat passive discovery (MNDP) as authoritative inventory.
 - Run write-shaped operations without an explicit target and validation policy.
 - Make generated output the hand-edited source of truth.
@@ -440,3 +542,9 @@ canonicalization only, never the structured-mode predicate. The gate contract,
 its pinning test, and the parser-vendoring preconditions are documented in
 `commands/execute/README.md` and the `canonicalizeExecuteCommand` doc-comment
 (`src/execute.ts`).
+
+Richer schema-free analysis must distinguish **ambiguous** (multiple plausible
+readings) from **unknown** (no safe reading) and abstain in both cases rather than
+inventing a command, path, symbol class, or transport mapping. These explain-only
+verdicts never widen or reinterpret the execution gate's `mode` or `writeShaped`
+decision.

package/docs/MATRIX.md

@@ -1,11 +1,15 @@
 # Matrix
 
-The product is a 2D grid of commands × protocols. This file is the **only**
-source of truth for what is done. No alpha gates, no milestones, no roadmap
-prose.
+This file owns **capability status and the selected work track**. The
+command × protocol grid covers live operations; offline analysis, frontends,
+and peer measurement have separate entries below. A capability's acceptance
+criteria live in its `commands/<name>/README.md`; GitHub issues own the tasks
+and dependencies that satisfy them.
 
-Pick the highest-priority cell that is not `CHR-passed`. That is the next
-work. See `docs/CONSTITUTION.md` for the cell-state definitions.
+Start with [Current priority](#current-priority), then the command's README,
+examples, and linked issue. Verification follows `docs/CONSTITUTION.md` →
+Done definition. A completed implementation slice is not proof that the whole
+capability is complete.
 
 ## Cell states
 
@@ -15,10 +19,15 @@ work. See `docs/CONSTITUTION.md` for the cell-state definitions.
 | `not-started` | No code and no design                                           |
 | `designed`     | `commands/<name>/README.md` describes intent and flags          |
 | `coded`        | Implementation exists in `src/`                                 |
+| `verified`     | Offline capability meets its command README's baseline acceptance criteria in full (examples, contract checks, measured/consumer gates, and CHR-grounded evidence). |
 | `CHR-passed`   | Every example in `commands/<name>/examples.md` is green on CHR  |
 
 A cell advances only with the matching evidence in the same change.
 
+`verified` applies to offline capabilities; it does not advance a live protocol
+cell. Existing `CHR-passed` fixture-backed `devices`/`settings` entries retain
+their command-specific evidence contracts.
+
 ## Grid
 
 | Command  | rest-api      | native-api    | ssh           | mac-telnet    | snmp          | mndp          | romon         | winbox-terminal |
@@ -31,13 +40,14 @@ A cell advances only with the matching evidence in the same change.
 | devices  | —             | —             | —             | —             | —             | —             | —             | —                |
 | discover | —             | —             | —             | —             | —             | `CHR-passed`  | —             | —                |
 | check    | `designed`    | `designed`    | `designed`    | `designed`    | `not-started` | `not-started` | `not-started` | `not-started`    |
+| explain  | `designed`    | `designed`    | —             | —             | —             | —             | —             | —                |
 | settings | —             | —             | —             | —             | —             | —             | —             | —                |
 
 ## Status pointers
 
 Detailed command contracts live in `commands/<name>/README.md`; example evidence
-lives in `commands/<name>/examples.md` and the named integration tests. Keep this
-section short enough that the grid remains the status surface.
+lives in `commands/<name>/examples.md` and the named tests. Keep task history
+and implementation sequencing in the linked issues.
 
 - `devices` is transport-less, so its row stays `—`; command state is
   `CHR-passed` by fixture-backed integration tests in `test/integration/devices.test.ts`.
@@ -59,6 +69,13 @@ section short enough that the grid remains the status surface.
   `winbox-terminal` stay `not-started`. Its per-host fan-out is the machinery the
   IP-scan discovery (#149) will iterate; the L2-default timing evidence (#136) is
   recorded in the README before the cells advance past `designed`.
+- `explain`'s two `designed` protocol cells are the future live probes
+  (`/console/inspect` + `:parse`, #236). The live grammar
+  (`explain <router> '<input>'`) is parsed and refused with
+  `usage/not-implemented`, never degraded to an offline run. Offline analysis
+  has its own capability entry below. The generated structure tables
+  `src/explain/menus.ts` and `src/explain/catalog.ts` keep analysis offline;
+  their ownership and regeneration contracts live in `commands/explain/README.md`.
 - `transfer / ssh` means the SFTP-backed transfer method. Deferred file-transfer
   methods such as `scp`, `fetch`, and `ftp` are tracked in
   `commands/transfer/README.md`; `fetch` is not a grid column.
@@ -71,9 +88,20 @@ section short enough that the grid remains the status surface.
 - Transport wire-format and delivery caveats belong in `src/protocols/*.ts`
   module headers. Do not expand this file with per-packet or per-router findings.
 
-Beyond the grid: post-`CHR-passed` hardening, ergonomics, and research work is
-tracked in GitHub issues (`dry-july` and successors). Those issues may point back
-to this matrix for current status, but they are not additional cell states.
+### Offline analysis
+
+This capability opens no protocol connection. It is usable independently and
+provides shared analysis for future integrations across the command grid.
+
+| Capability | State | Contract and evidence | Work |
+| ---------- | ----- | --------------------- | ---- |
+| explain / offline baseline | `verified` | `commands/explain/README.md` → Offline baseline acceptance; offline examples in `test/unit/explain.test.ts`, focused `test/unit/explain-*` suites, and CHR captures under `test/fixtures/explain/`. The token partition is scored against device `highlight` by `test/unit/explain-highlight-agreement.test.ts` and `test/fixtures/explain/highlight-agreement.json`. The public entry is `@tikoci/centrs/explain`; its dependency boundary and executed browser-consumer proof are gated by `test/unit/explain-browser-entry.test.ts` (`bun run explain:browser-consumer`). #322's fixed-size 16× depth guard and deterministic structural-work guards close the bounded-execution criterion. | #90 indexes correctness, token agreement (#264/#263), consumer verification, and bounded execution (#322). |
+
+The CLI/library expose structure, diagnostics, token partitions, symbols, and
+flow-sensitive value facts. `verified` records the offline acceptance evidence;
+it is not a parser-coverage score and does not advance either live protocol cell.
+Live probes (#236), MCP response alignment (#223), and future configuration
+policies are distinct work, not prerequisites for using offline analysis.
 
 ### Transport-base readiness
 
@@ -89,13 +117,13 @@ single home for wire-format, auth, and delivery facts.
 
 ### Frontend surfaces (orthogonal to the command grid)
 
-The grid tracks the core (commands × protocols). Frontends are adapters over that
-core and carry their own state, tracked here:
+Frontends adapt the shared analysis and device-operation core and carry their
+own state, tracked here:
 
 | Surface | State | Spec | Notes |
 | ------- | ----- | ---- | ----- |
 | ts-api | `CHR-passed` | `src/index.ts` | Root TypeScript library surface; everything else adapts it. |
-| cli | `coded` | `src/cli/` | `retrieve`/`execute`/`transfer`/`terminal`/`devices`/`discover`/`btest` wired. |
+| cli | `coded` | `src/cli/` | Every command in `cliCommands` (`src/cli.ts`) is wired: `retrieve`/`execute`/`api`/`transfer`/`terminal`/`explain`/`devices`/`discover`/`btest`/`mcp`/`settings`, plus the `upload`/`download` shortcuts. |
 | mcp | `CHR-passed` | `commands/mcp/` | Scoped-verb stdio MCP server; details in `commands/mcp/README.md` and `test/integration/mcp.test.ts`. |
 | tui | `not-started` | `src/tui.ts` | Stub. |
 | proxy | `not-started` | `src/webproxy.ts` | Stub. |
@@ -120,11 +148,57 @@ its own capability axis and is exempt from the RouterOS command-validation gate.
 Wire, auth, TCP/UDP, and CI caveats live in `commands/btest/README.md` and the
 `src/protocols/btest*.ts` / `src/protocols/ec-srp5.ts` module headers.
 
-## Priority order
-
-Do not start a later item until the earlier cell or dependency checkpoint has
-matching evidence. The grid above is the live status; per-item detail lives in
-the linked `commands/<name>/`.
+## Current priority
+
+**Tightening validation as a whole** is the selected track, in the three-step
+order agreed on [#236](https://github.com/tikoci/centrs/issues/236):
+
+1. **Done** — fix the offline false rejects so the analyzer can be trusted as a
+   gate (#347/#348, shipped in #349; the measured corpus false-reject count went
+   4 → 1).
+2. **Done** — front the `execute` / `api` device preflight with the offline
+   analyzer (#354). The gate is now two-stage; the contract is in
+   [`docs/CONSTITUTION.md` → Validation is the product](CONSTITUTION.md#validation-is-the-product).
+3. **Next** — **live `explain` (#236)**, as stage two of a gate that now exists.
+   Start with [the #90 task index](https://github.com/tikoci/centrs/issues/90),
+   then follow [`commands/explain/README.md`](../commands/explain/README.md) and
+   the live examples in
+   [`commands/explain/examples.md`](../commands/explain/examples.md).
+
+The offline baseline stays `verified`: #264 closed the measured token vocabulary
+and #322 closed the final bounded-execution gap, including the public depth-axis
+guard.
+
+The live pass is the device-backed cross-check on the offline result, not a
+replacement for it. It adds read-only `/console/inspect` and `:parse` evidence,
+the describe/completion facets, and the live `observedType`/`schemaType`
+producers owned with #225. REST and native-api cells advance only when their
+applicable examples pass on CHR via `bun run test:integration`.
+
+Open offline follow-ups remain explicit but do not reopen the verified baseline.
+Issue #211 retains the fail-closed unlisted-path decision; #272 owns
+non-authoritative `.scratch/` citation cleanup. #350 (the broad optional `=`,
+schema-dependent and so belonging to step 3), #351 (an unresolvable menu that
+abstains at 2-deep nesting but hard-fails at 3-deep) and #355 (`'` is not a
+RouterOS token — a false ACCEPT the corpus join cannot see) are bounded analyzer
+defects that step 2 now surfaces through the `execute`/`api` gate. #336 and #342 are complete: the
+corpus is repinned to three *complete* builds (long-term 7.23.5, stable 7.24.2,
+development 7.25beta3), and the operator sweep and highlight slice are re-swept
+onto those same builds — plus 7.21.5 retained as an age anchor — so the operator
+axis and the token partition are scored on the same firmware. The #335
+source refresh pins both architectures of those versions beside the 7.10.2 /
+7.16 history anchors and accepts the current CLI-Reference drift. Issue #223 is
+a separate MCP response migration. If live evidence finds a wrong offline
+assertion, give that defect a bounded issue and matching CHR-grounded controls
+rather than folding it silently into the live implementation.
+
+Unfinished SNMP, RoMON, TUI, or other protocol/frontend cells do not preempt this
+track. Change this selection when the maintainer selects another track.
+
+### Protocol backlog order
+
+Retained for protocol work when selected; this is not a dependency chain for
+offline analysis. Per-item detail lives in the linked `commands/<name>/`.
 
 1. **retrieve / rest-api** — `CHR-passed` (`commands/retrieve/`).
 2. **CDB resolution + metadata overrides** — `CHR-passed` (`commands/devices/`).

package/docs/errors/README.md

@@ -47,6 +47,9 @@ Codes are slash-namespaced `family/slug`. The families and where they originate:
 - `input/*` — malformed caller input (paths, MACs, arguments).
 - `internal/*` — centrs bugs / unreachable states.
 - `mndp/*` — MNDP wire codec and listener (`src/data/mndp.ts`).
+- `quickchr/*` — the quickchr named-live-provider (`--quickchr <name>`): optional
+  package availability, descriptor version support, and machine lookup/liveness
+  (`src/resolver/quickchr-provider.ts`).
 - `routeros/*` — RouterOS-surfaced faults mapped by the grounded vocabulary in
   `src/core/routeros-errors.ts` (REST `detail` and native-api `!trap`, identical
   on CHR 7.23).

package/docs/errors/quickchr/machine-not-found.md

@@ -0,0 +1,22 @@
+# `quickchr/machine-not-found`
+
+No quickchr machine is registered under the name passed to `--quickchr <name>`.
+
+## Typical trigger
+
+The name does not match any machine quickchr knows about — a typo, a machine
+that was never created, or one that has been removed. centrs raises this both
+when `QuickCHR.get(name)` returns nothing and when the descriptor call reports
+quickchr's own `MACHINE_NOT_FOUND`.
+
+## Fix
+
+- List the registered machines with `quickchr list` and pass an existing name.
+- Create/start the machine first if it does not exist yet (`quickchr start
+  <name>`).
+- Names are exact — check for typos and case.
+
+If the machine exists but is not running, you will see
+[`quickchr/machine-stopped`](./machine-stopped.md) instead.
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) → Resolution providers.

package/docs/errors/quickchr/machine-stopped.md

@@ -0,0 +1,20 @@
+# `quickchr/machine-stopped`
+
+The named quickchr machine exists but is not running, so it has no live
+connection facts (host, forwarded ports, credentials) for centrs to dial.
+
+## Typical trigger
+
+`--quickchr <name>` named a real machine, but its VM is stopped. quickchr only
+knows the forwarded loopback ports and running-state auth while the machine is
+up, so a stopped machine cannot yield a `ServiceEndpointMap`.
+
+## Fix
+
+- Start it: `quickchr start <name>`, then retry `--quickchr <name>`.
+- Confirm state with `quickchr list` / `quickchr inspect <name>`.
+
+This is a per-target failure: in a fan-out over several `--quickchr` targets,
+one stopped machine fails only its own row, not the whole run.
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) → Resolution providers.

package/docs/errors/quickchr/package-unavailable.md

@@ -0,0 +1,27 @@
+# `quickchr/package-unavailable`
+
+The optional `@tikoci/quickchr` package is not installed, so a `--quickchr
+<name>` target cannot be resolved into connection facts.
+
+## Typical trigger
+
+You passed `--quickchr <name>` (or otherwise resolved a quickchr target) in an
+install that does not have `@tikoci/quickchr`. centrs declares it as an
+**optional dependency** and loads it through a runtime import, so a normal
+install without it works for every non-quickchr path and only fails here.
+
+## Fix
+
+- Install the package: `bun add @tikoci/quickchr` (0.4.5+ — 0.4.4 introduced
+  the descriptor v1 API but advertises dead TLS endpoints on a stock CHR;
+  see quickchr#95).
+- Or bypass quickchr entirely and target the device directly with `--host`
+  (plus `--username`/`--password`/`--ssh-key` or a CDB record).
+
+This code is raised **only** when the module is genuinely not found. An
+installed package that throws while loading reports
+[`quickchr/unsupported`](./unsupported.md) instead, so the two are never
+confused.
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) → Resolution providers for
+the named-live-provider contract.

package/docs/errors/quickchr/unsupported-via.md

@@ -0,0 +1,35 @@
+# `quickchr/unsupported-via`
+
+The quickchr machine resolved fine, but the chosen `--via` has no usable
+service on it. The descriptor is per-service; centrs reads exactly the
+endpoint for the chosen protocol and never falls back to another transport.
+
+## Typical trigger
+
+Any of:
+
+- The `--via` is a protocol the descriptor does not forward. quickchr v1
+  forwards `rest-api`, `native-api`, and `ssh` only — `mac-telnet`, `romon`,
+  `btest`, and `winbox-terminal` are never available on a quickchr target.
+- The service exists but quickchr marked it `available: false` (the error
+  carries the provider's `unavailableReason`).
+- `--via ssh` (or `transfer --via sftp`/`scp`): the SSH endpoint reports no
+  batch-capable auth mode (`batchModes` is empty), so a non-interactive
+  handoff is impossible. centrs fails typed here rather than prompt for a
+  password or silently pick another transport.
+
+## Fix
+
+- Pick one of the machine's live services; the error's `availableServices`
+  context lists them (typically `--via rest-api` / `--via native-api` /
+  `--via ssh`).
+- For the SSH/sftp gate, verify key-based login works from quickchr's side
+  (`quickchr ssh <name>`); once quickchr has a verified key, the descriptor
+  advertises `private-key` in `batchModes` and centrs will use it.
+- If the machine should be forwarding the service but is not, inspect it with
+  `quickchr inspect <name>`.
+- To use a transport quickchr does not forward, target the device directly
+  (`--host`/CDB record) instead of `--quickchr`.
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) → Resolution providers for
+why a provider's missing service is a typed error, never a silent fallback.

package/docs/errors/quickchr/unsupported.md

@@ -0,0 +1,35 @@
+# `quickchr/unsupported`
+
+The installed `@tikoci/quickchr` cannot give centrs a usable descriptor: it is
+too old to expose the descriptor API, it failed to load, or it emitted a
+descriptor centrs cannot read.
+
+## Typical trigger
+
+Any of:
+
+- The installed quickchr predates the `QuickCHR.get(name).descriptor()` API
+  (before 0.4.4), so the descriptor entry point is missing.
+- The package is installed but throws while loading (a broken/partial install),
+  which is a real fault — distinct from
+  [`quickchr/package-unavailable`](./package-unavailable.md), which means "not
+  installed at all".
+- The descriptor is malformed or pre-v1: no numeric `descriptorVersion`, no
+  `services` map, or missing `name`/`version`/`arch`. centrs rejects it rather
+  than crash on a later field access or silently treat `services` as empty
+  (which would hide a provider contract violation).
+- The descriptor version is **newer** than centrs supports
+  (`descriptorVersion` > 1); a newer quickchr speaks a schema this centrs
+  predates.
+
+## Fix
+
+- Upgrade quickchr to a release that emits descriptor v1: `bun add
+  @tikoci/quickchr` (0.4.5+ — 0.4.4 has the API but a descriptor endpoint
+  bug, quickchr#95).
+- If the descriptor looks wrong, inspect the machine directly with `quickchr
+  inspect <name>` — it may be in a transient state.
+- If the descriptor is newer than centrs supports, upgrade centrs.
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) → Resolution providers for
+the descriptor contract and the supported version boundary.

package/docs/errors/routeros/version-unsupported.md

@@ -0,0 +1,26 @@
+# `routeros/version-unsupported`
+
+The device's RouterOS version does not provide the operation this command
+needs. centrs pre-flighted the generated command against the device's known
+version (a live read, or the stored CDB `version=` fact) and refused it before
+touching the router, instead of letting the device return a raw protocol
+error.
+
+Distinct from `routeros/unsupported-capability`, where the chosen *protocol*
+cannot carry the operation at all regardless of device version.
+
+## Context fields
+
+- `capability` — stable slug of the missing operation.
+- `version` — the device version that was checked.
+- `versionSource` — `live`, `cdb-fact`, or `caller`. A `cdb-fact` version is
+  stale-by-nature; it was recorded by `discover --save` or `devices --check`.
+- `supported` — the version windows where RouterOS provides the operation
+  (inclusive `min`, optional exclusive `maxExclusive` for backport windows).
+
+## Fix
+
+Upgrade RouterOS to one of the versions listed in `supported`. If the device
+was already upgraded and the check used a stale stored fact
+(`versionSource: "cdb-fact"`), refresh the record's `version=` comment fact
+and retry.

package/docs/errors/transport/provider-trust.md

@@ -0,0 +1,29 @@
+# `transport/provider-trust`
+
+A warning (not an error): the target came from a named-live-provider
+(`--quickchr <name>`), and centrs relaxed peer verification to use its
+endpoint.
+
+## Why this happens
+
+quickchr's descriptor prefers the VM's TLS forwards (`https` / `api-ssl`),
+whose certificate is the CHR's own self-signed one, and its SSH endpoint's
+host key is regenerated per VM. The descriptor carries no trust material, so
+strict verification would reject every quickchr target and force `--insecure`
+ceremony onto every lab call.
+
+Instead, centrs treats the endpoint as **trusted by provenance**: quickchr
+vouches for a loopback-forwarded port (`127.0.0.1:<port>`) of a VM the user
+owns, so peer verification is relaxed for exactly that connection — with
+`provider` provenance on `meta.settings.insecure` and this warning on the
+envelope, never silently.
+
+## When to care
+
+- If this warning appears on a target you did **not** select with
+  `--quickchr`, that is a bug — report it.
+- The relaxation never applies to CDB, literal, or env-resolved targets;
+  those still require an explicit `--insecure` (which raises
+  [`transport/insecure-trust`](./insecure-trust.md) instead).
+
+See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) → Resolution providers.