@dx-do/cli 6.0.1 → 6.0.4

package/dist-node/{metrics-grounding-2h4kkbe3.md → metrics-grounding-8vhfqya9.md}

@@ -10,7 +10,7 @@ related: [metric-source-names, mm-cookbook, mm-quickstart, entity-relationships,
 
 `mm-quickstart` and `mm-cookbook` cover the *mechanics* of authoring metric-metadata queries. This cookbook covers the **semantics** — what a metric *means* in DXO2's entity model, how to navigate from a metric back to the producing agent (or accept that no entity exists), and how to handle the most common surprise: metrics for resources that have no topology vertex.
 
-## Metric identity, four ways
+## Metric identity, five ways
 
 The same metric is referred to by different names depending on which surface you're on:
 
@@ -20,6 +20,7 @@ The same metric is referred to by different names depending on which surface you
 | MM `SourceNameSpecifier` + `AttributeNameSpecifier` | Metrics-Metadata query input |
 | `<resource>:<metric>` | User shorthand — the `metric.path` ending after the last `:` is the metric name; the prefix is the "resource" |
 | `metric.attribute` (older) | Older API field — alias for the path's leaf segment |
+| `metric.attributes.external_ids` | TAS-compatible vertex externalIds carried on every metric descriptor — the entity-association field. An array because a metric can be associated with multiple vertices. Round-trips with `FROM_TOPOLOGY`'s `VERTEX` filter without reformatting. See worked examples `42-metadata-metric-id-to-entities` (metricId → externalIds) and `34-nassql-entity-to-metric-ids` (externalId → metricIds). |
 
 Concretely, a metric like `Beans|Nass Reactive Client|Store|Flush|Unregistered Queue:Concurrent Invocations` carries:
 
@@ -60,11 +61,65 @@ The metric *value* is sometimes the only place identity lives — e.g. a `queue_
 
 When this pattern repeats for the same customer / same kind of resource, **inventorize** materializes a vertex per resource so future queries can use vertex traversal. See `lexicon/inventorize`.
 
-## Metric `type` is opaque (for now)
+## Metric `type` is a bitmask — what the bits mean
 
-Every metric carries a numeric `type` field with values like `0`, `1`, `2`, `3`. The numeric ID indicates the metric's data shape (gauge, counter, rate, etc.) and informs how it should be aggregated and displayed.
+Every metric carries a numeric `type` field. It is **not** an enum value — it is a 32-bit integer composed by bitwise-OR of one or more named `typeEnum` values. A `type` of `268436481` decodes to `MONITOR_INT_DURATION` combined with `TYPE_INFO_FRONTEND` (`0x401 | 0x10000000`).
 
-**The numeric → semantic mapping is not yet documented in the corpus.** Treat `metric.type` as opaque: when you need to aggregate or order, prefer empirical inspection of values via `run_partial_query` rather than assuming a particular type means a particular aggregation. A future grounding pass will close this gap.
+### Bit-region layout
+
+| Region mask | Purpose |
+|---|---|
+| `0x0000000F` | underlying type — INT (1), LONG (2), DOUBLE (4), STRING (5) |
+| `0x000000F0` | type-property bits (server-internal flags) |
+| `0x000FFF00` | numeric-info bits — DURATION (0x400), RATE (0x200), COUNTER (0x100), PERCENTAGE (0x1000), INTERVAL_COUNTER (0x2000), SATURATION (0x4000) |
+| `0x00F00000` | counter-info bits (server-internal counter flags) |
+| `0x0F000000` | metric flags — TYPE_FUTURE (0x01000000), TYPE_VIRTUAL (0x02000000), TYPE_TAGS (0x04000000) |
+| `0xF0000000` | metric-type info — TYPE_INFO_FRONTEND (0x10000000), TYPE_INFO_BACKEND (0x20000000), TYPE_INFO_BUSINESS_TRANSACTION (0x40000000) |
+
+### `typeEnum` value table
+
+| typeEnum | hex | decimal |
+|---|---|---|
+| `MONITOR_INT_DURATION` | `0x00000401` | 1025 |
+| `MONITOR_LONG_DURATION` | `0x00000402` | 1026 |
+| `MONITOR_INT_RATE` | `0x00000201` | 513 |
+| `MONITOR_LONG_RATE` | `0x00000202` | 514 |
+| `MONITOR_PERCENTAGE` | `0x00001001` | 4097 |
+| `MONITOR_INT_INTERVAL_COUNTER` | `0x00002001` | 8193 |
+| `MONITOR_LONG_INTERVAL_COUNTER` | `0x00002002` | 8194 |
+| `MONITOR_DOUBLE_INTERVAL_COUNTER` | `0x00002004` | 8196 |
+| `MONITOR_INT_SATURATION` | `0x00004001` | 16385 |
+| `MONITOR_LONG_SATURATION` | `0x00004002` | 16386 |
+| `MONITOR_STRING` | `0x00000005` | 5 |
+| `MONITOR_INT_COUNTER` | `0x00000101` | 257 |
+| `MONITOR_LONG_COUNTER` | `0x00000102` | 258 |
+| `MONITOR_DOUBLE_COUNTER` | `0x00000104` | 260 |
+| `TYPE_FUTURE` | `0x01000000` | 16777216 |
+| `TYPE_VIRTUAL` | `0x02000000` | 33554432 |
+| `TYPE_TAGS` | `0x04000000` | 67108864 |
+| `TYPE_INFO_FRONTEND` | `0x10000000` | 268435456 |
+| `TYPE_INFO_BACKEND` | `0x20000000` | 536870912 |
+| `TYPE_INFO_BUSINESS_TRANSACTION` | `0x40000000` | 1073741824 |
+
+To check bit math: `composeMetricTypeBits(['MONITOR_INT_DURATION', 'TYPE_INFO_FRONTEND'])` from `@dx-do/client` returns `268436481`. The reverse is `decodeMetricTypeBits(n)`, which returns `{ matched, residual }` — a non-zero residual means the integer carries server-internal bits outside the user-facing typeEnum API (see `gotchas.md` — undocumented `MONITOR_DOUBLE_*` variants).
+
+### Filtering metrics by typeEnum
+
+Use the `TYPE` AttributeNameSpecifier:
+
+```json
+{
+  "op": "TYPE",
+  "bitMask": 1024,
+  "bitMatch": 1024,
+  "operator": "EQ",
+  "specifier": { "op": "ALL" }
+}
+```
+
+This catches every metric where bit 10 is set — i.e. any DURATION variant (INT, LONG, or undocumented DOUBLE). For an exact typeEnum filter set `bitMask = bitMatch = composeMetricTypeBits([...])`. The `specifier` field is required by the server even though the schema marks it optional — see `gotchas.md`.
+
+The visual MM query editor's TYPE-op chips picker writes both fields (and the inner `specifier`) automatically when you select typeEnum names. For "any of this semantic class regardless of INT / LONG / DOUBLE", pick from the **`ANY_*` group** at the top of the dropdown — e.g. `ANY_DURATION` produces the bit-10-only mask above, `ANY_RATE` produces bit 9, etc. The `MONITOR_*` chips remain pinned to a specific underlying type; picking both `MONITOR_INT_DURATION` and `MONITOR_LONG_DURATION` is **not** the same as `ANY_DURATION` — the chips combine with AND semantics, so that pair composes to a mask no real metric satisfies. Use `ANY_DURATION` for the "INT or LONG or DOUBLE" intent.
 
 ## Pattern recognition: deciding when to inventorize
 

package/dist-node/{mm-cookbook-23jpw721.md → mm-cookbook-fdwbt989.md}

@@ -59,7 +59,7 @@ so each component has its own specifier sub-language with its own ops.
 | `OR` | `{ op: "OR", specifiers: [...] }` | Union |
 | `NOT` | `{ op: "NOT", specifier: ... }` | Complement |
 | `SPEC` | `{ op: "SPEC", sourceNameSpecifier?, folderNameSpecifier?, attributeNameSpecifier? }` | Structured match (the workhorse) |
-| `ID` | `{ op: "ID", ids: ["m-id-1", ...] }` | By metric id |
+| `ID` | `{ op: "ID", ids: ["m-id-1", ...] }` | By metric id. The response's `metric.attributes.external_ids` array carries TAS-compatible vertex externalIds — the entity-association field. See worked example `42-metadata-metric-id-to-entities` for the metricId → entity round-trip. |
 | `ATTRIBUTE` | `{ op: "ATTRIBUTE", expressions: [...] }` | By metric-attribute expression |
 | `GROUP` | `{ op: "GROUP", id?, managementModuleId? }` | By management module / group |
 | `SERVICE` | `{ op: "SERVICE", values: [...] }` | By named service |

package/dist-node/{nassql-cookbook-n8kc0mff.md → nassql-cookbook-kp525xra.md}

@@ -26,7 +26,7 @@ flowchart LR
   src["source: FROM_TOPOLOGY / FROM_METADATA / FROM / FROM_DATA"] --> joins["joins (optional): JOIN_TOPOLOGY / JOIN_METADATA / JOIN_DATA"]
   joins --> transforms["transforms: GROUP / FILTER / WINDOW / MAP_STRING / FORMAT_TIME / DISTINCT / ORDER"]
   transforms --> aggs["aggregations: COUNT / SUM / MEAN / TOP / BOTTOM / FIRST / LAST / QUANTILE / AGG"]
-  aggs --> shape["shape: KEEP (always last)"]
+  aggs --> shape["shape: KEEP (optional; last if used)"]
 ```
 
 Mental model: a **dataframe pipeline**. Source ops produce rows with named
@@ -186,6 +186,14 @@ After a `FROM_TOPOLOGY` source, join in metric metadata for those vertices.
 `joinType`: `INNER` (default) | `LEFT`. Use `LEFT` when you want to keep
 vertices that have no metrics (rows with null metric columns are retained).
 
+**Scope to one entity (metric inventory for a named vertex).** A common
+recipe — `FROM_TOPOLOGY` filtered to one `externalId` with `VERTEX`,
+followed by `JOIN_METADATA(ALL)` and `KEEP vertex.externalId, metric.id`
+— enumerates every metric an entity emits. Worked example:
+`34-nassql-entity-to-metric-ids`. The inverse direction (metricId →
+the externalIds of associated entities) is `42-metadata-metric-id-to-entities`,
+via the `metric.attributes.external_ids` array on every metric descriptor.
+
 ### `JOIN_TOPOLOGY`
 
 Inverse: after a metadata source, join the topology for the metrics' source
@@ -260,9 +268,41 @@ Filter rows by a `QueryFilterPredicateSpec`. Predicate ops:
 
 String-based filter expression for cases the predicate spec cannot express.
 
+Operators: `&&` (AND), `||` (OR), `!` (NOT), `== != < <= > >=`, `matches` (regex). String literals use single quotes.
+
+The visual editor's FILTER_EXPR helper offers these same examples as one-click templates — keep them synchronized when either side gains a new pattern. (Longer-term, the editor should load examples from this file rather than maintaining its own list.)
+
+Worked examples:
+
+```json
+{ "op": "FILTER_EXPR", "spec": "metric_count > 100" }
+```
+*Numeric threshold — keep rows where a numeric column passes a threshold.*
+
+```json
+{ "op": "FILTER_EXPR", "spec": "metric.source matches '.*prod.*'" }
+```
+*String regex on a metric attribute — anchor with `^…$` for a full match; otherwise treated as substring.*
+
 ```json
 { "op": "FILTER_EXPR", "spec": "metric_count > 100 && metric.source matches '.*prod.*'" }
 ```
+*Compound (AND) — combine clauses with `&&` (AND) or `||` (OR).*
+
+```json
+{ "op": "FILTER_EXPR", "spec": "used > capacity * 0.9" }
+```
+*Column-vs-column — both sides can reference columns and arithmetic.*
+
+```json
+{ "op": "FILTER_EXPR", "spec": "!(metric.source matches '.*staging.*')" }
+```
+*Negation — wrap any expression with `!(…)` to negate it.*
+
+```json
+{ "op": "FILTER_EXPR", "spec": "metric.environment == 'prod'" }
+```
+*String equality — single quotes for string literals; `==` for equality, `!=` for inequality.*
 
 ### `ORDER`
 

package/dist-node/{nassql-quickstart-090e0yex.md → nassql-quickstart-mth22qd3.md}

@@ -28,7 +28,7 @@ The `FROM_METADATA` vs `FROM` confusion is the most-confused single distinction
 
 ## Schema landmines (READ FIRST)
 
-1. **`KEEP` must be the LAST op.** Anything after KEEP returns HTTP 400. Put projection at the end of the pipeline; do GROUP / FILTER / sorting before.
+1. **`KEEP`, when used, must be the LAST op.** KEEP itself is **optional** — many pipelines end with `AGG` / `COUNT` / `TOP` / `BOTTOM` / `DESCRIBE` and have no KEEP at all. But anything that follows a KEEP returns HTTP 400. If you do project, put KEEP at the end and do GROUP / FILTER / sorting before it.
 2. **`TOP` and `BOTTOM` use `n`, not `count`.** `{op:"TOP", column:"x", n:10}` — schema field is exactly `n`. The intuitive `count: 10` parses but rejects.
 3. **`GROUP`, `ORDER`, `KEEP` cannot have empty `columns`.** Schema enforces `.min(1)`. Same for `FILTER`'s `AND`/`OR` `spec` arrays.
 4. **`JOIN_TOPOLOGY` does NOT take a `querySpecifier`** — it joins by pipeline data via `externalIdColumn`, not by a TAS specifier. Surprising compared to JOIN_METADATA.
@@ -39,6 +39,8 @@ The `FROM_METADATA` vs `FROM` confusion is the most-confused single distinction
 9. **TOP and BOTTOM have asymmetric `sortAscending` defaults.** TOP defaults to `false` (largest first); BOTTOM defaults to `true` (smallest first). Setting `sortAscending: true` on TOP is legal but produces BOTTOM-equivalent ordering — switch the op for clarity.
 10. **`GROUP` only drops non-grouped columns when followed by an aggregator.** `GROUP → AGG` collapses to grouping-key + `as` outputs; `GROUP → BOTTOM/TOP/ORDER/KEEP/FILTER` (no aggregator) preserves the upstream column shape. Use `KEEP` after GROUP if you want pruning without aggregation.
 11. **Diagnostic: verify a FROM matches anything before pulling on the full pipeline.** Run `[FROM, KEEP({columns:["metric.id"]})]` in isolation; zero data rows → the specifier matches no metric in this tenant. The data-store editor's "Run JUST this step" control on FROM / FROM_METADATA does this for you.
+12. **`COUNT` after `GROUP` requires an explicit `as`.** Schema marks `as` optional with default `"count"`, but the server returns HTTP 400 for a bare `{op:"COUNT"}` immediately after `GROUP`. Always set `as` on COUNT (e.g. `{op:"COUNT", as:"n"}`). Treat `as` as required in practice. See `cookbooks/gotchas` for the full schema-vs-server discrepancy note.
+13. **TAS ATTRIBUTE expression `name` is `type`, NOT `_type`.** `_type` is a storage-side / NASSQL specifier convention; using it inside a TAS ATTRIBUTE filter is accepted by the schema (the schema allows any string) but silently returns zero rows. Same for `hostname`, `agentType`, etc. — use the user-facing attribute key, not the storage field. See `cookbooks/gotchas`.
 
 ## The envelope
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dx-do/cli",
-  "version": "6.0.1",
+  "version": "6.0.4",
   "description": "CLI execution of DX Operational Observability operations and triage",
   "author": "Ki Alam",
   "logo": {