@tikoci/centrs 0.1.4 → 0.1.7

package/CHANGELOG.md

@@ -6,7 +6,423 @@ The product evolves as a stream of changes; there are no alpha gates.
 Per-feature status is tracked in `docs/MATRIX.md`. Use this file for
 documenting cross-cutting shifts that affect contributors and consumers.
 
-## Unreleased
+## 0.1.7 — 2026-09-27
+
+### Added
+
+- **`centrs devices init` creates an empty CDB, `git init`-style (#376).**
+  Bootstrapping a device book previously meant conjuring the file some other
+  way. `centrs devices init [--cdb-file PATH]` (or `CENTRS_CDB_FILE`, or the
+  default path) creates the parent directories and an exclusive `0600` file.
+  **It never clobbers**, so a bootstrap script may run it unconditionally: an
+  existing readable CDB succeeds with a `cdb/file-exists` warning and nothing
+  is written. An existing file that fails to load (`cdb/parse-failed`,
+  `cdb/password-required`) reports that error and is left untouched, and a
+  location that cannot be written fails with the new `cdb/create-failed`. CLI
+  and library (`initCdb`) only; not exposed on the MCP devices tool.
+
+- **`devices list` reports the lookup keys it matches on (#378).** Rows now
+  carry `identity` / `mac` / `ip` when the comment sets them, with
+  `comment-kv` provenance in `sources`, and the text table gains an `IDENTITY`
+  column. `comment` itself stays `show`-only.
+
+### Fixed
+
+- **Write-shaped commands now require confirmation, on every transport
+  (#365, #366).** Write authorization was entangled with script-vs-structured
+  transport selection, so several shapes reached a device without passing the
+  `--yes` gate: selectors, positional ids, non-CRUD verbs, root mutators,
+  indirect execution and relative menu writes. Authorization is now decided
+  independently of how the command is carried. Read spellings are unaffected —
+  the verb is the first known verb among the path's last segment and the bare
+  words following the path token, so `/system identity print` and
+  `:put [/system identity get name]` stay reads, while a statement with no
+  recognizable verb still fails closed. Caller-addressed API `/execute` script
+  strings additionally run offline analysis, then live `:parse`, then execute;
+  structured API requests remain on `/console/inspect`. This advances the
+  synchronous half of #154 without closing it — caller-controlled `file=`,
+  `as-string` and async job-id semantics remain open there.
+
+- **RouterOS rejections returned inside a successful transport envelope are no
+  longer read as success.** `/execute` can answer 200 while the device's own
+  text says it refused. Those are now classified as runtime failures, with the
+  passed validation-stage history preserved so the envelope still shows what
+  each stage concluded.
+
+- **Device-stage validation missed RouterOS's bare `missing …` diagnostics
+  (#375).** `classifyParseResult` matched `syntax error`, `bad command name`
+  and `expected …` from `:put [:parse …]`, but not `missing closing brace` or
+  `missing value for where` — so the device stage reported those rejections as
+  a pass and the command ran. `/ip/address/find where=` passes offline, which
+  made the device classifier its only gate. Replaying every bare diagnostic in
+  the pinned corpus across 7.20.8 → 7.25beta3 finds exactly seven heads, and
+  the two `missing …` forms were the only misses; both are now recognized, with
+  the device's own position in `error.context.detail`. Echoed script text is
+  still not a verdict.
+
+- **A stream's `/cancel` acknowledgement is now bounded (#385).** `api
+  --stream` stopped by `--duration` or Ctrl-C sent `/cancel` and then waited
+  with no bound, so a connected router that never answered held the CLI open
+  forever — `backend.close()` in the outer `finally` was unreachable while that
+  wait was pending. The wait is now bounded by the request `--timeout`, the
+  same bound as every other reply wait; past it the listen ends locally and the
+  session closes. The summary keeps its real `stopReason` and adds a
+  `transport/cancel-unacknowledged` **warning**, so the outcome never claims an
+  acknowledgement that did not arrive. A cooperating router is unchanged.
+
+- **`retrieve --attributes` rejected real singleton properties (#377).**
+  `isKnownSingletonPath` knew only `/system/resource` and `/system/identity`,
+  so every other singleton (`/tool/romon`, `/system/routerboard`, `/ip/dns`, …)
+  was inspected as a list menu. `print,proplist` comes back empty on a
+  singleton, so validation fell back to `print`'s own flags (`as-value`,
+  `file`, `interval`, …) and offered those as the attribute list. The singleton
+  bit now comes from the device: a singleton's `get` takes only `value-name`,
+  while a list menu's `get` also takes `number`. The hardcoded pair survives
+  only as the `--validate=false` fallback, which skips inspect. Costs one extra
+  `request=child` for a menu that has `get`.
+
+- **Completion candidates mixed help text and syntax rows into property names
+  (#380).** `extractCompletionNames` read `completion`/`name`/`value`/`text`
+  from every row, so the help string ("DNS cache size in kB") and the
+  `show: "false"` syntax rows (`[`, `(`, `$`, `"`, `*`, `<value>`) were offered
+  as attributes — which is why `--attributes '$'` passed validation. Rows carry
+  only `completion`/`offset`/`preference`/`show`/`style`/`text`/`type` on every
+  build recorded 7.9.2 → 7.25beta3, so `name`/`value` never matched anything.
+  On CHR 7.23.7, `show: "true"` is exactly the property set. The exported
+  `InspectCompletionItem` drops the never-present `name`/`value` and adds
+  `show`/`style`/`offset`/`preference`.
+
+- **An unparseable `<router>` crashed instead of reporting (#381).**
+  `parseHostCandidate` passed the target straight to `new URL` — the only
+  `new URL` on user input in `src/` — so with the default CDB, `quickchr:NAME`,
+  `a b` or `bad:host:name` failed every command with a `TypeError: Invalid URL`
+  surfaced as `internal/unhandled`. It now raises `input/invalid-target` and
+  names the valid target forms; a `quickchr:NAME` guess is told to use
+  `--quickchr NAME`. With an explicit CDB the same input already stopped at a
+  classified `cdb/not-found-target`, so that path is unchanged.
+
+### Changed
+
+- **The pinned restraml inspect trees advance to the live channel builds.** The
+  pins named "current stable" and "next beta" while pointing a patch behind
+  both: stable 7.24.2 → 7.24.4 and development 7.25beta3 → 7.25beta5. History
+  anchors 7.10.2 and 7.16 are untouched and both current versions stay
+  architecture-paired. The refresh is structurally a no-op — the inspect union
+  holds at 617 menus and the catalog at 1,120 paths, with no path added or
+  removed and no kind change. What moved is current-only publication: the CLI
+  Reference grew 1,053 → 1,055 pages (1,060 → 1,062 entries) and now documents
+  `/interface/ethernet/pon` and `/ip/ssh/known-hosts`, so both move `inspect` →
+  `both` (961 `both`, 65 `inspect`, 94 `published`). Zero
+  navigation-vs-command contradictions, unchanged.
+
+## 0.1.6 — 2026-09-15
+
+### Changed
+
+- **Release channels now use standard npm pre-release versions, not the even/odd
+  minor rule.** `0.1.x` counted as "pre-release" only by an internal convention
+  npm could not see, so every cut since 0.1.0 published to `next` and `latest`
+  was left pointing at 0.1.0 — a plain `npm install @tikoci/centrs` handed you a
+  June build while six releases sat on `next`. The dist-tag is now selected by
+  the SemVer pre-release identifier: a `-`-suffixed version (`0.1.7-next.0`)
+  publishes to `next` and never moves `latest`; a plain version (`0.1.6`)
+  publishes to `latest` and carries `next` forward with it, so `@next` cannot
+  resolve older than `@latest` between cuts. This release is the first plain
+  version under the new rule, so `latest` and `next` both land on 0.1.6 — which
+  is also the fix for the stale `latest`. The pre-1.0 caveats are unchanged:
+  this is still an early preview, and `docs/MATRIX.md` remains the source of
+  truth for what works.
+
+- **Validation now runs offline first, then on the device.** centrs had two
+  validators that did not know about each other: the device preflight
+  (`:put [:parse …]` + `/console/inspect request=child`) that `execute` / `api` /
+  `validate` share, and offline `explain`, which was byte-accurate and
+  corpus-gated but took no part in validation at all. `execute` (all four
+  transports) and `api`'s `/execute` script mode now run the analyzer as
+  **stage 1**, before any connection: a syntax fault comes back with the
+  offending byte span in `error.context.span` and the protocol adapter is never
+  dialed, where `:put [` previously cost a full round trip to be told no. The
+  `api /execute` carve-out is the larger change — that surface ran **no**
+  preflight at all, so its script went to the device ungated.
+  `meta.validation.stages[]` reports what each stage concluded and names a
+  skipped stage's reason, so a reader can tell "the device accepted it" from
+  "the device was never asked". Stage 1 is necessary and never sufficient: it
+  has no per-menu schema, so it cannot see an unknown attribute, and the device
+  stage is unchanged. An offline `warn` is an abstention and passes through;
+  only a `fail` rejects. `--validate=false` disables both stages — one flag, one
+  meaning (#354, and the ordering agreed on #236).
+
+### Fixed
+
+- **`'` is not a RouterOS token, and offline analysis now says so (#355).** `'`
+  is not a string delimiter and not a legal bare byte — only `"` opens a string.
+  `:parse` rejects `name=don't`, `name=don't'`, `name='abc'` and `:put 'abc'`
+  byte-identically on CHR 7.21.5, 7.23.5, 7.24.2 and 7.25beta3, and offline
+  `explain` passed all four with ZERO diagnostics, dropping the byte into
+  `unclassified`. It now raises `explain/canonicalizer/invalid-apostrophe` on
+  the apostrophe's own byte — which is the device's own reported column in every
+  case — while an apostrophe inside a `"`-string or a comment stays legal. Rows
+  2-4 above carry BALANCED apostrophes and are rejected anyway, so this is a
+  lexical rule and not a quote-balance one. Being a false ACCEPT, it was
+  invisible to the corpus false-reject join, which scores one direction only.
+  Over the pinned corpus the rule fires on 40 scripts and every one is
+  device-rejected: the false-reject count is unchanged at 1 and the caught count
+  goes 62 → 93. Symbol resolution stops at the apostrophe too, the way it
+  already stopped at a malformed escape, so `:put 'abc'; :put $after` no longer
+  publishes an occurrence for `$after` — that returns 306 bytes to
+  `unclassified` and is the only census movement; value, operator and
+  bracket-equals are unchanged.
+- **The quote-count preflight that modelled `'` as a delimiter is gone.**
+  `execute` carried a private `hasUnbalancedQuotes` check, moved into the
+  offline gate by #354 and kept there only because it was the one thing catching
+  the apostrophe case. It had no comment awareness, so an English contraction in
+  a `#` comment opened a quote it never closed — over the pinned corpus it
+  false-rejected **51** of the 617 scripts CHR 7.24.2 accepts, a figure the
+  published measurement never saw because that measurement ran `explainCommand`
+  rather than the whole gate. Removing it costs 21 catches, all on scripts the
+  device rejects anyway and where the device stage still applies, and takes the
+  gate's false rejects from 52 to 1.
+
+- **CI: the three console reads that RouterOS 7.23.6/7.24.3/7.25beta4 broke.**
+  Those builds print a settings menu that has exactly one property — of the
+  menus centrs reads, only `/system/identity` — one character per line, so
+  `name: CHR` comes back with `C`, `H` and `R` on three lines under the label.
+  It is neither a terminal-width effect nor transport-specific: REST `POST /rest/execute` wraps identically to the
+  ssh and mac-telnet consoles, and every multi-property `print` is unaffected
+  (measured on stock CHR 7.24.2 vs 7.24.3). `execute --via ssh`,
+  `execute --via mac-telnet`, and `terminal --via ssh` now assert the identity
+  they read with `print` column wrapping collapsed on both sides, so the
+  examples are evidence about the console round-trip rather than about a
+  device layout MikroTik is free to change (#352).
+- **CI: the CHR image cache now rotates with the RouterOS point release.**
+  `actions/cache` only writes on an exact-key miss, so the old static key froze
+  the first image it ever saw: every stable bump was re-downloaded from
+  download.mikrotik.com on *every* job and never saved. A 186s cold download
+  duly timed out the 300s `chr-smoke` test on the 7.24.2 → 7.24.3 bump. The key
+  now carries the version the job will boot (`scripts/chr-cache-key.ts`), the
+  smoke test gets the headroom a cold download needs, and the QA leg's own
+  timeout absorbs one — a cold download had also been cancelling a whole
+  channel leg mid-suite with every assertion green (#352).
+
+## 0.1.5 — 2026-09-15
+
+*Tagged but never published: the release-tier CHR sweep failed on the
+7.23.6/7.24.3 console-wrap and image-cache defects that #352 then fixed, so npm
+has no 0.1.5. Everything below shipped in 0.1.6.*
+
+### Added
+
+- **Offline `explain`'s token partition is now scored against the device.**
+  `bun run explain:highlight-agreement` projects each centrs token class onto
+  the RouterOS `/console/inspect request=highlight` class it predicts and
+  reports where the two agree, over the committed capture slice — no router, no
+  corpus, no network. The report separates what it can score from what it
+  cannot: each side's abstentions, and the tail after the device's own one-byte
+  `error` — half the slice's bytes, where 7.23.2 falls silent for the rest of
+  the script and 7.24rc2 mostly does. A second axis says why an answer was out of reach — offline-decidable,
+  schema-dependent, state-dependent or version-dependent — assigned per byte
+  from context rather than by class name, since one highlight class carries more
+  than one category. Representative source fragments ship with the counts.
+  Figures are a trend line over a known-biased corpus, never a pass threshold
+  (#264 B4, #263).
+
+### Fixed
+
+- **Offline `explain` no longer rejects two RouterOS spellings every tested
+  build accepts.** Measured, not guessed: running the analyzer over all 948
+  corpus scripts and comparing to each build's own `:parse` verdict found four
+  device-accepted scripts that offline analysis hard-failed, identical on
+  7.23.5, 7.24.2 and 7.25beta3. They were two language gaps, and both are now
+  fixed — the count is 1, and the one that remains is the device tolerating a
+  genuinely extra `}`, where explain is arguably the stricter of the two.
+  - A scope slot may drop the `=` before its brace: `:if (…) do={…} else {…}`
+    and `do {…}` are the same construct as the documented `else={…}` form.
+    `:parse` lowers all of the spellings to byte-identical IL on CHR 7.21.5,
+    7.23.5, 7.24.2 and 7.25beta3, with `elsy {` rejected on all four as the
+    control. Only the four `SCOPE_ARG_NAMES` members may drop it, so
+    `:local z {1;2}` still reads its brace as an array literal, and a colon
+    disqualifies the word — the device parses `do {…}` but refuses `:do {…}` in
+    an argument slot, since a colon makes it a directive (#347).
+  - A relative menu-scope block composes the path: `/ip { address { print } }`
+    is `(evl (evl (evl /ip/address/print)))` on the device, and a block body may
+    open with a submenu, one of the thirteen frozen CRUD verbs, a scripting
+    directive, or an absolute command. The absolute spelling already worked; the
+    nested relative one hard-failed. An unknown menu still does not become a
+    pass — the catalog's "a miss says nothing" contract means it abstains rather
+    than being claimed either way (#348).
+
+  As a side effect the offline token partition agrees with the device on 8 more
+  bytes of the committed slice, all of them moving out of *offline-silent* into
+  *agree*, with no new disagreements.
+
+- **`centrs api --raw` no longer silently discards an explicit `--validate`.**
+  `--raw` short-circuited the whole settings ladder, so `--raw --validate=true`
+  ran no preflight at all — and `CENTRS_VALIDATE`, the CDB comment-kv override
+  and config lost to it just as quietly. It is now a precedence layer: the
+  explicit `--validate` flag wins, then `--raw`, then the ambient sources, then
+  the `true` default. `--raw` alone is unchanged and still behaves identically
+  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) — the intended way
+  to debug `api` when centrs itself is the suspect (#154).
+
+- **`execute`/`api` validation no longer probes command-level
+  `request=completion`.** On RouterOS 7.12.2 that request shape never answers:
+  REST hangs past the client timeout (then surfaces the router's own session
+  close mislabeled as `validation/syntax`) and the native API closes the
+  connection outright, so every validated call — plain reads included — failed
+  on that build while `--no-validate` succeeded instantly. The attribute set
+  those two commands check against now comes from command-level
+  `request=child` alone, through the shared `inspectArgumentNames` helper;
+  `child` returns the complete argument list in single-digit milliseconds on
+  the same 7.12.2 controls, so nothing is lost by dropping the union.
+  `meta.validation.source` reads `/console/inspect request=child`.
+  `retrieve` is unchanged — its argument-level completion probe
+  (`print,proplist` / `get,value-name`) is a different request shape and
+  answers normally on 7.12.2 (#343).
+- **The reported package version is the real one.** The library's
+  `centrsVersion` and the MCP `initialize` handshake both announced a
+  hard-coded `0.1.0` regardless of what was published, so a bug report from an
+  MCP client named the wrong build. Both now derive from `package.json`
+  through `src/core/version.ts`, and a unit test holds them to it (#343).
+- **Offline `explain` no longer invents a verb for a menu path with
+  arguments.** `/ip/firewall/address-list name=ytkids timeout=1h` reported
+  `resolved`, path `/ip/firewall`, verb `address-list` — and the spaced
+  spelling `/ip firewall address-list name=x` promoted `firewall`, one level
+  higher still. Both premises were already offline facts and both said no: the
+  whole run is a known menu, and the promoted segment is not a console verb.
+  The reading is now an `ambiguous` abstention with a located diagnostic saying
+  which menu and which segment. Priced on the frozen dev/holdout partition, 10
+  of 17,212 statements flip, every one of them a fabrication withdrawn — three
+  real RouterOS statements missing their verb and seven lines of pasted
+  non-RouterOS prose. Presence in the shipped structure tables still narrows a
+  reading and absence still decides nothing, so an unlisted menu is read
+  exactly as before (#324).
+- **Offline `explain`'s token partition reaches inside a command
+  substitution.** `:put "$[/ip address print as-value]"` came back as one
+  opaque `string` run over a command `data.structure.subcommands` already
+  reported as resolved, so an editor rendering `data.tokens[]` painted an
+  interpolated string flat. The path fill was being handed a span computed as
+  "one byte inside the brackets", which is wrong for `$[…]` (the sigil is part
+  of the span) and for `[ … ]` (the inner text is trimmed); both spellings now
+  carry a published `innerSpan` instead. Byte coverage does not move — what
+  moves is which fill owns those bytes (#325).
+
+### Changed
+
+- **Every live fixture is re-swept onto the current release channels.** The
+  operator sweep was pinned to 7.23.3 stable / 7.24rc4 testing / 7.21.5
+  long-term and the highlight slice to 7.23.2 / 7.24rc2 — none of them a
+  current channel, and none a build the corpus covers with both oracles, so the
+  operator axis and the token partition were never scored on the same firmware.
+  Both now run on the three builds the corpus classes `complete`: stable
+  **7.24.2**, long-term **7.23.5**, development **7.25beta3**. The slice bases
+  on stable, where development serializes as `null` throughout and only the 33
+  long-term splits cost bytes. The sweep keeps **7.21.5** as a fourth build,
+  explicitly an age anchor rather than a channel claim — it is the only live
+  evidence that the operator surface behaves the same on a pre-7.23 branch, and
+  dropping it would have retired a fact rather than refreshed one (#342, #336).
+- **The live sweep independently reproduces the corpus's channel split.**
+  Highlight agreement is byte-identical between stable and development in every
+  bucket and differs on long-term — the same shape the corpus IL showed at
+  87/11 and 33/0. Two oracles, two capture paths, same conclusion.
+- **Array comparison is not fixed on current long-term.** `:put ({2;1} >
+  {1;2;3})` evaluates on 7.24.2 and 7.25beta3 and errors on 7.23.5 and 7.21.5.
+  7.23.5 is *newer* than the 7.23.3 this was first measured on and still errors,
+  so the change rode the 7.24 line and was never backported —
+  `ARRAY_COMPARISON_NOTE` now says so. The device's post-`error` recovery flipped
+  with the same realignment: `parser-recovered` is 0 on long-term and 96 bytes
+  on both stable and development.
+
+- **The bracket-`=` abstention figure is generated and gated instead of
+  asserted.** `commands/explain/README.md` and `src/explain/operator-tokens.ts`
+  both quoted a `224` / `1,259` / `1,035` split for the cost of leaving `=`
+  inside `[ … ]` unclaimed. No script produced it, no `:check` gated it, and no
+  universe reproduces it — it was written once in PR #292 and had been prose
+  ever since, which is exactly the condition a corpus repin can silently
+  invalidate. `bun run explain:bracket-equals` now derives it, with `--check`
+  and `--readme --check` gates on the corpus → fixture → README chain like the
+  other censuses, and the README block is generated. Measured: **1,079** `=`
+  bytes inside `[ … ]` across 263 of 948 scripts, **1,067** left
+  `unclassified` — **448** genuine `find`/`where` query comparisons against
+  **619** plain `arg=value`. The `arg` fill rescues **none** of them, contrary
+  to the obvious guess, because it offers only the `=` its own located argument
+  token names. The query reading is the device's: on 7.24.2, 93 of the 109
+  scripts that parsed carry at least as many `(= …)` IL nodes, and the
+  shortfalls are scripts whose enclosing menu the capture build could not
+  resolve (#341).
+
+- **The operator census reads only version-comparable RouterOS builds.** The
+  corpus is repinned to `lsp-routeros-ts` `7d62355` (schema v4), which carries
+  three *complete* builds — long-term 7.23.5, stable 7.24.2 and development
+  7.25beta3, each with both oracles over all 948 scripts — beside six partial
+  captures covering 913. The census summed occurrences across every version it
+  found, so the added build inflated every head count by ~20% while
+  `distinctScripts`, the column carrying the argument, did not move at all. It
+  now filters on the new `v_version_coverage.coverage_class = 'complete'` view,
+  giving a rectangular universe of 2,841 parse-IL rows — 3 builds × the 947 of
+  948 scripts that produce IL — and states its version set so a gate cannot
+  compare two different universes. Presence *is* monotone in coverage, so
+  the partial builds keep one job: a new `headFirstSeen` axis dates each head
+  against every captured build — which is what still grounds the `any` operator
+  at 7.20.8, a build the counting side no longer reads. `source_scripts` is
+  byte-identical across the repin, so every text-derived report — the token and
+  value censuses, `explain:arg-reach`, the browser-consumer proof — is
+  unchanged by construction (#336, #342).
+- **The three complete builds are recorded as disagreeing.** `:parse` IL differs
+  on 87 of 948 scripts between long-term 7.23.5 and stable 7.24.2 but on only 11
+  between stable and development 7.25beta3; `highlight` differs on 33 and 0. So
+  an operator-axis or token-partition figure is a claim about a *channel*, not
+  about RouterOS, and `commands/explain/README.md` now says so rather than
+  collapsing the builds to one number.
+- **A valid string escape is now its own token class in offline `explain`.**
+  `ExplainTokenClass` gains `escaped`, the second and last split #264's rule
+  admits: only INVALID escapes surfaced anywhere else, as `bad-string-escape`
+  diagnostics, so a consumer holding `tokens[]` had no published surface to join
+  against to find the valid ones — and the device names them. The escape grammar
+  is not walked a second time to do it: `walkStringEscapes` now returns both
+  halves of the one reading `bad-string-escape` already came from, so a token
+  and a diagnostic cannot disagree about which bytes are an escape, and it stops
+  claiming at the first invalid escape rather than guess past a malformed one.
+  **Byte coverage does not move** — classified bytes are identical to the last
+  decimal; `escaped`'s 19,960 corpus bytes come out of `string` (−17,672) and
+  `value` (−2,288) exactly, and the token count rises only because a run
+  carrying an escape becomes three. Against the committed device slice the class
+  agrees on 418 of 418 bytes and the `unprojected` residue falls 1,051 → 633.
+  Consumers reading `data.tokens[]` for `string` or `value` must now also read
+  `escaped` to see bytes they used to get inside one run. A `\`-newline line
+  continuation in **code** is deliberately not claimed — the device calls it
+  `escaped` too, but its run swallows the next line's indentation, and what a
+  continuation owns is #225's question (#264).
+
+- **Offline `explain`'s token vocabulary is no longer provisional, and the
+  argument `=` has its own class.** `ExplainTokenClass` gains `arg-sep`: an
+  argument's name bytes stay `arg`, and the single `=` binding it to its value
+  is now named separately. #264 B5 settled the whole vocabulary on a stated
+  rule — a merged class is split only where a consumer needs the distinction
+  AND cannot recover it by joining `tokens[]` to another published surface on
+  byte offsets — so the per-spelling `operator`, per-shape `value`,
+  scope-versus-array `brace` and string-delimiter merges stay merged, each with
+  the surface that already carries the distinction named. The `=` was the one
+  that failed the test: 30.8% of the `=` runs the fill paints (5,088 of 16,526
+  on the pinned corpus) belong to a statement whose strict `arguments` reading
+  refused, led by the `do=` of every `:if`/`:foreach`/`:while`, so there is no
+  published `valueSpan` to derive the boundary from. **Byte coverage does not
+  move** — classified bytes are identical to the last decimal; this is a retag,
+  and the token count rises only because one run became two. Against the
+  committed device slice, projection disagreements fall 360 → 2 as centrs stops
+  calling a separator a name. Consumers reading `data.tokens[]` for `arg` must
+  now also read `arg-sep` to see the bytes they used to get in one run
+  (#264 B5, #316).
+
+- **Offline `explain` answers statement-ownership from an index, not a scan.**
+  The symbol/value surface asked "which statement owns this span" once per
+  symbol, value and scope brace by scanning every statement split, so cost grew
+  quadratically with symbol-dense input: 253 KiB of declarations took 4.3 s and
+  was still steepening. Output is unchanged — all 1,896 `explainCommand` hashes
+  over the pinned corpus match byte for byte under both facet settings — and the
+  growth-ratio guard now covers a symbol-dense input shape alongside the
+  separator-free one (#317).
 
 ## 0.1.4 — 2026-08-31
 

package/GLOSSARY.txt

@@ -149,10 +149,12 @@ npk # MikroTik package format
 nvme-over-tcp # supported by RouterOS **with** rose-storage.npk extra-package
 OID
 PII # Personally Identifiable Information
+PON # passive optical network; RouterOS /interface/ethernet/pon menu
 POV
 PRGA
 proplist
 pywinauto
+QKD # quantum key distribution; RouterOS IPsec/keymat-provider vocabulary
 QML
 qll # CodeQL library file extension (.qll), e.g. CleartextLoggingCustomizations.qll
 qmljsdebugger
@@ -384,6 +386,16 @@ evl
 # as "(evl /putmessage=x)", ":global n v" as "(evl /globalname=$n;value=v)" (GH#230).
 putmessage
 globalname
+# localname/setnote/runnumber: more of the same head rendering, quoted verbatim as
+# evidence for the missing-separator rule (GH#311). ":put [:parse …]" joins the IL
+# array with NO separator, so the path and its first argument run together —
+# ":local a v" is "(evl /localname=$a;value=v)", "/system/note set note=hello" is
+# "(evl /system/note/setnote=hello)", "/system/script/run /ip/route" is
+# "(evl /system/script/runnumber=/ip/route)". Artefacts of the rendering, not
+# RouterOS argument names; kept unsplit because the quote must match the bytes.
+localname
+setnote
+runnumber
 # unconfigured: a freshly-flashed RouterOS device with no IP — the mac-telnet use case.
 unconfigured
 unwired
@@ -676,6 +688,7 @@ mmips # RouterOS architecture (multi-core MIPS), named in `conditions:` gates
 CRS # MikroTik Cloud Router Switch — carries the switch-chip menus no CHR has
 CCR # MikroTik Cloud Core Router
 superlinear # growth faster than linear, used for resolveDocument wall-clock on separator-free input (#248)
+superlinearity # the property a growth-ratio guard bounds; `superlinear+` is NOT usable here, cspell's compound form forbids the bare word (#313)
 stmts # `explainCommand` corpus measurement: statement count (shorthand for `statements`)
 argCandidates # `explainCommand` corpus measurement: arg-bearing candidates
 argReadable # `explainCommand` corpus measurement: readable statements
@@ -691,7 +704,7 @@ llms # `llms.txt` — MikroTik's published page inventory; the only one listing
 musicswitch # syscap gate: the Marvell-era switch-chip menu shape — one half of the `/interface/ethernet/switch` pair published under two gates
 rbswitch # syscap gate: the RouterBOARD switch-chip menu shape — the other half of that pair
 prestera # Marvell Prestera switch chip — named in the `crs_prestera` syscap gate on `/interface/ethernet/switch/qos`
-xfrm # `/interface/xfrm` — the IPsec transform interface, and the one published path with no gate anywhere in its ancestry to explain its absence from a CHR tree
+xfrm # `/interface/xfrm` — the IPsec transform interface, device-confirmed by the pinned 7.25beta3 trees and published by the CLI Reference
 btrfs # the Linux B-tree filesystem, a `/disk/btrfs/...` menu on RouterOS 7.20+
 
 # #255 operator-axis vocabulary: the device-grounded operator surface.
@@ -718,3 +731,29 @@ occ # short for occurrence — local variable in symbol-values flow analysis
 vid # short for valueId — result-local value occurrence identifier (v0, v1)
 idx # short for index — loop/event index in flow merging
 mis # prefix in mis-linking — hyphenated in comments for symbol-values guard
+
+# #313 offline performance vocabulary
+JIT # just-in-time compiler — warmed before either half of the growth-ratio timing so the two sizes are compared in the same compilation state
+
+# #317 statement-ownership index vocabulary
+laminarity # the property of a set of spans in which every pair is nested or disjoint, never crossing — what makes the shortest containing span reachable by a parent walk
+
+# #264 B4 / #263 device-agreement vocabulary
+unprojected # of a byte whose offline/device class PAIR the declared projection does not cover, so it can neither agree nor disagree: an offline class that deliberately maps to no RouterOS `highlight` class, or a device class this build has never seen (#264 B4)
+
+# #324 / #325 offline-reading vocabulary. Both words are corpus data: they are
+# quoted from the two slice scripts the device-agreement report names as the
+# exemplars of the cells these fixes empty, so their spellings must match the
+# bytes the device saw.
+ytkids # an address-list name in the corpus line `/ip/firewall/address-list name=ytkids timeout=1h` — the #324 exemplar
+apikey # a local variable in the corpus line `apikey-len=$([:len $apikey])` — the `$(…)` interpolation #325 deliberately leaves unreached
+
+# #312 offline-entry boundary vocabulary
+dgram # Node's `node:dgram` UDP socket module — reached by `mac-telnet`, and one of the builtins that made the old `explain` import graph unusable outside Bun; named in the boundary gate's allowlist rationale
+
+# #347 / #348 offline false-reject controls. Both words are deliberate
+# NON-words: each is the rejected half of a CHR-confirmed accepted/rejected
+# pair, so its spelling is load-bearing and must not be "corrected".
+elsy # the misspelled `else` in `:if (1=1) do={…} elsy {…}` — rejected as `expected end of command` on CHR 7.21.5/7.23.5/7.24.2/7.25beta3, which is what proves the bare-brace `else {` acceptance is a real device fact and not a probe artifact (#347)
+prnt # a misspelt `print` verb — `/ip/address/prnt` is the offline analyzer's ABSTENTION fixture (`verdict: warn`, not `fail`), which is what proves the two-stage validation gate passes an abstention through to the device rather than refusing it (#354)
+zzznotamenu # a menu name no RouterOS build has — `/ip { zzznotamenu { print } }` is a `syntax error` on device, so menu-scope resolution is schema-dependent and a catalog MISS must abstain rather than accept (#348)

package/README.md

@@ -11,9 +11,13 @@ installing centrs or connecting to a router:
 bunx @tikoci/centrs@next explain '/ip/address print' --json
 ```
 
-Use `bunx @tikoci/centrs@next --help` to inspect the full preview CLI. The
-explicit `@next` matters: `0.1.x` preview releases do not move npm's `latest`
-tag.
+Use `bunx @tikoci/centrs@next --help` to inspect the full preview CLI. Since
+0.1.6 the dist-tag follows standard SemVer semantics rather than the old
+even/odd-minor rule: a plain version (`0.1.6`) publishes to `latest` and carries
+`next` forward with it, while a pre-release suffix (`0.1.7-next.0`) publishes to
+`next` only and never moves `latest`. So `@next` is the leading edge and can
+equal `@latest` between cuts — `npm view @tikoci/centrs dist-tags` is the
+authority.
 
 The full flag reference for every command is generated from the CLI metadata
 into [`docs/CLI.md`](docs/CLI.md); per-command behavior lives in
@@ -58,7 +62,7 @@ product; without them this would just be a worse `curl`.
 | `execute`  | Run RouterOS CLI-shaped read/write commands (add/set/remove) over native API/REST/L2 surfaces. |
 | `api`      | Structured RouterOS API passthrough (gh-api style): one command per operation, structured in/out, can write, over REST or native API. Open-ended follow is `api … --stream` (native API; NDJSON). |
 | `terminal` | Open an interactive console, primarily SSH or MAC-Telnet. |
-| `check`    | Probe reachability and management protocol availability. |
+| `check`    | Probe reachability and management protocol availability. **Designed, not implemented** — see `docs/MATRIX.md`. |
 | `explain`  | Analyze a RouterOS command before running it: canonical form, syntax diagnostics, and what is valid at a path. Offline analysis runs today; the live-device probes are designed. |
 | `devices`  | View and maintain the CDB-backed device registry (the only writer). |
 | `discover` | Discover MNDP neighbors and optionally save them into the CDB. |
@@ -178,7 +182,9 @@ and the comment grammar — lives in `commands/devices/README.md` and
 
 The load-bearing contract — envelope shape, error model, protocol selection,
 settings precedence, and the "done" definition — lives in
-`docs/CONSTITUTION.md`. The command×protocol status grid is `docs/MATRIX.md`.
+`docs/CONSTITUTION.md`. Capability status and the selected work track,
+including the command×protocol grid and offline analysis, live in
+`docs/MATRIX.md`.
 
 ## Repository layout
 
@@ -187,13 +193,15 @@ code and authority docs live.
 
 - **`docs/CONSTITUTION.md`** — load-bearing rules (validation, envelope, error
   model, settings precedence, identity/CDB, protocol selection, done).
-- **`docs/MATRIX.md`** — command×protocol grid; the only status surface.
+- **`docs/MATRIX.md`** — capability status and the selected work track (the
+  command×protocol grid plus offline analysis and frontend surfaces); the
+  only status surface.
 - **`commands/<name>/`** — per-command README and executable examples.
 - **`src/`** — Bun/TypeScript source.
 - **`test/`** — unit and CHR-backed integration tests.
 
-There is no `docs/specs/`, no `work/`, no roadmap doc. The matrix is the
-roadmap.
+There is no `docs/specs/`, no `work/`, no roadmap doc. The matrix and the
+GitHub issues it links are the roadmap.
 
 ## Development
 

package/commands/AGENTS.md

@@ -3,9 +3,11 @@
 Each `commands/<name>/` holds the **executable spec** for one command:
 
 - `README.md` — intent, flags, behavior. The "designed" tier.
-- `examples.md` — numbered, runnable examples. Each example is one assertion in
-  the matching `test/integration/<name>.test.ts`; example N ↔ assertion N. This
-  is what `CHR-passed` is measured against.
+- `examples.md` — numbered, runnable examples mapped to named tests:
+  example N ↔ named test N. Live examples require CHR integration; offline
+  examples use the unit/fixture tests named by the command — a named test may
+  carry several assertions. Verification follows `docs/CONSTITUTION.md` →
+  Done definition.
 
 **Implemented** flags are generated from `CliCommandMetadata` into
 `docs/CLI.md` (`bun run docs:cli`; drift-gated in CI) — a command README keeps
@@ -19,7 +21,8 @@ keys, ambiguity, `__default__`, comment-kv allowlist, write strategy) lives in
 `commands/devices/README.md` — the registry command owns it; the constitution
 keeps only the identity/CDB principle. A command file covers only what is
 specific to that command. `docs/MATRIX.md` is the only status surface; a
-README's "Status" line must agree with it.
+README's "Status" line must agree with it. GitHub issues track the tasks and
+dependencies within the selected capability; they do not replace its status.
 
 ## Verb vocabulary
 

package/commands/api/AGENTS.md

@@ -183,11 +183,23 @@ green on CHR 7.23.1.
   not `print`/`get`), so it is a `POST` and **write-classed** → needs `--yes`.
 - **CONFIRMED — the inspect gate over both transports.** Path existence
   (`request=child` empty ⇒ `validation/unknown-path`) and add/set attribute
-  validity (`request=child`+`completion` ⇒ `validation/unknown-attribute`) fire
+  validity (`request=child` ⇒ `validation/unknown-attribute`) fire
   identically over rest-api and native-api, **before** any write — no `:put
   [:parse]` involved (api input is a path, not a CLI string). A `/execute` script
   is a CLI string ⇒ `meta.validation.semantic = "not-applicable"`.
 
+## CONFIRMED ON CHR (RouterOS 7.12.2 compatibility — GH#343, 2026-09-14)
+
+- **Command-level `request=completion` is unsafe on 7.12.2.** For
+  `path=system,identity,print`, REST did not answer before the 10 s client
+  timeout and native API closed the connection immediately. Adding
+  `.proplist=completion` did not change either result. The preceding `:parse`
+  and `request=child` controls returned in 1–8 ms on both transports, and
+  `child` contained the complete command argument list. Execute/API attribute
+  validation therefore uses command-level `request=child` only. This does not
+  prohibit argument-level completion probes such as `print,proplist`, which are
+  a separate shape and returned immediately on the same 7.12.2 controls.
+
 ## CONFIRMED ON CHR (Phase 4 `--stream` follow — CHR 7.23.1, 2026-06-30)
 
 Validated by `test/integration/api-listen.test.ts` (L1–L4) on CHR 7.23.1.