@dx-do/cli 5.2.48 → 5.2.50

package/README.md

@@ -4,10 +4,32 @@
 
 ***
 
-### Usage
+## Usage
 
 :warning: Using npm install for this package is highly discouraged.
 
+The first time you run, an interactive setup will create <USER_HOME>/.dxdo/default.dxo2.config.json; you can have multiple configurations.  the "--config=<config>" has the following resolution:
+
+
+| variation                                 | resolution                             |
+|-------------------------------------------|----------------------------------------|
+| No Config Specified                       | `~/.dxdo/default.dx02.config.json`     |
+| `--config=tenant-name`                    | `~/.dxdo/tenant-name.dx02.config.json` |
+| `--config=tenant-name.dx02.config.json`   | `~/.dxdo/tenant-name.dx02.config.json` |                                      |
+| `--config=./tenant-name.dx02.config.json` | `<CWD>/tenant-name.dx02.config.json`   |                                     
+
+### Full configuration options are available by running 
+
+```dx-do --no-config help configuration```
+
+### via binary
+
+1. Download the binary for your platform
+2. rename to "dx-do" and add to path
+
+```
+dx-do <--config=<config-file>> command-group command <parameter>=<value>
+```
 
 # via npx
 
@@ -20,16 +42,12 @@ npx @dx-do/cli@<version> <--config=<config-file>> command-group command <paramet
 bunx @dx-do/cli@<version> <--config=<config-file>> command-group command <parameter>=<value>
 ```
 
-# via binary
 
-```
-dx-do <--config=<config-file>> command-group command <parameter>=<value>
-```
 
 #### Output
 
 ```
-ℹ  info      dx-do v5.2.46 on node v22.21.0 on darwin-arm64 via node (ssl: 3.5.4)
+ℹ  info      dx-do v5.2.50 on node v24.16.0 on linux-x64 via node (ssl: 3.5.6)
 ⚠  warning   Not loading configuration
 ✖  error     Usage: dx-do --option[=value]... <command-group> <command> <command-param>=<value>...
 ℹ  info      Available command-groups: acc, agent, agentic, alarm, alert, apm-universe, asm, attribute, audit, auth, axa, blob, channel, config, dashboard, diagnose, event, experience, graph, help, inventory, jsextension, log, managementmodule, metrex, metric, metricgrouping, nass, o2-alert, o2-managementmodule, o2-metricgrouping, o2-universe, perspective, service, situation, sql, tas, topographer, trace, ui, vertex

package/dist-node/01-discover-vertices.tas-pwngv2fz.md

@@ -0,0 +1,31 @@
+# 01-discover-vertices (TAS)
+
+## Purpose
+
+Fetch a sample of topology vertices with full attribute detail to understand what vertex types exist on the tenant and what attributes they carry.
+
+## Query Construction
+
+Uses the simplest possible TAS query: `ALL` filter with `DETAILED` projection and a `limit` of 20. The `DETAILED` projection includes all gathered, custom, and decorated attributes on each vertex.
+
+## API Surface Exercised
+
+- **Filter**: `ALL` (the baseline — matches every vertex)
+- **Projection**: `DETAILED` (returns all attributes, not just type/name)
+- **Limit**: Caps result size for discovery
+
+## Expected Output
+
+A `TasGraph` with up to 20 vertices, each containing:
+- `id` (numeric internal ID)
+- `externalId` (canonical string identifier)
+- `attributes` map with keys like `type`, `name`, `hostname`, `ACNId`, etc.
+- `startTime` / `endTime` timestamps
+
+No edges are returned because the default query only retrieves vertices unless traversal or edge-adding filters are used.
+
+## What the Results Tell You
+
+The `type` attribute reveals what kinds of entities are in the topology: `HOST`, `AGENT`, `BUSINESSTRANSACTION`, `k8s_POD`, `INFERRED_DATABASE`, etc. The attribute names on each vertex type tell you what fields are available for filtering (e.g., `hostname`, `agentName`, `applicationName`).
+
+Typical vertex types include: HOST, AGENT, AGENT_CONNECTION, BUSINESSTRANSACTION, INFERRED_DATABASE, PRODUCT, DXI_SERVICE, CONNECTOR, ACN_CONFIG, MYSQL_DB, k8s_CLUSTER, k8s_NAMESPACE, k8s_DEPLOYMENT, k8s_DAEMONSET, k8s_POD, k8s_CONTAINER. The exact set varies by tenant — what's installed and reporting is what shows up here.

package/dist-node/01-discover-vertices.tas.data-store-svjfrm1f.json5

@@ -0,0 +1,29 @@
+/*
+ * Discovery query #1 — sample 20 vertices with FULL attribute detail
+ * to learn what's on this tenant. The pattern: cheapest possible
+ * filter (`ALL`), tightest sensible cap (`limit: 20`), widest
+ * projection (`DETAILED`). Reach for this when you're new to a
+ * tenant and need to see what vertex types and attributes exist
+ * before authoring anything specific.
+ *
+ * Pair with `02-discover-services` (filtered to top-level types) to
+ * learn the topology shape without burning a 10MB topology dump.
+ */
+{
+  /*
+   * `ALL` is the only zero-cost filter — matches every vertex with
+   * no expression evaluation. SAFE here ONLY because `limit: 20`
+   * caps the response. WITHOUT `limit`, an `ALL` filter returns
+   * the entire topology (often megabytes). Don't author this shape
+   * without `limit`.
+   */
+  "filter": { "op": "ALL" },
+  "limit": 20,
+  /*
+   * `DETAILED` returns all gathered, custom, and decorated
+   * attributes per vertex. The alternatives are `BRIEF` (just type
+   * + name) and `NO_TYPE`. For discovery you almost always want
+   * `DETAILED` — that's the point of running this query.
+   */
+  "projection": "DETAILED"
+}

package/dist-node/01-discover-vertices.tas.data-store-tmd-w650nfzt.json

@@ -0,0 +1,4 @@
+{
+  "description": "Discovery: fetch 20 vertices with full attributes to understand vertex types and attribute shapes",
+  "tags": ["discovery", "tas"]
+}

package/dist-node/02-discover-services.tas-867m0m88.md

@@ -0,0 +1,30 @@
+# 02-discover-services (TAS)
+
+## Purpose
+
+List vertices of the most common topology types to understand what agents, hosts, services, and applications exist on the tenant.
+
+## Query Construction
+
+Uses the `ATTRIBUTE` filter with the `IN` operator on the `type` attribute, matching: `AGENT`, `HOST`, `DXI_SERVICE`, `BUSINESSTRANSACTION`, `INFERRED_DATABASE`, `PRODUCT`. Returns up to 100 vertices with full detail.
+
+## API Surface Exercised
+
+- **Filter**: `ATTRIBUTE` with `expression.operator = "IN"` — matches vertices where the named attribute's value is in the provided list
+- **Projection**: `DETAILED`
+
+## Expected Output
+
+A `TasGraph` with up to 100 vertices matching the requested types. Each has full attributes including `name`, `type`, `hostname`, agent paths, etc.
+
+## What the Results Tell You
+
+A typical small tenant might return something like:
+- **3 HOSTs**: VMs / nodes hosting the workload
+- **7 AGENTs**: Kubernetes, Infrastructure, MySQL, Logstash, Prometheus, etc.
+- **11 BUSINESSTRANSACTIONs**: web app endpoints (signon, checkout, cart, …)
+- **2 INFERRED_DATABASEs**: e.g. MySQL backing the same app
+- **1 PRODUCT**: e.g. APM
+- **1 DXI_SERVICE**: e.g. a Custom Metric virtual agent
+
+The actual names returned depend entirely on what's installed and reporting on the tenant — use these as inputs to subsequent targeted filter queries.

package/dist-node/02-discover-services.tas.data-store-jz0gx5vn.json5

@@ -0,0 +1,40 @@
+/*
+ * Discovery query #2 — list some top-level vertex TYPES on the
+ * tenant. Where #1 samples 20 random vertices, this targets the
+ * shape: AGENT / HOST / DXI_SERVICE / BUSINESSTRANSACTION /
+ * INFERRED_DATABASE / PRODUCT. Reach for this when you need to
+ * understand what categories of entities the tenant has + how many
+ * of each, before drilling into one.
+ *
+ * Pair with `01-discover-vertices` (random sample, full attributes)
+ * for a complementary view: #1 tells you "what exists in detail",
+ * #2 tells you "what TYPES exist in volume".
+ */
+{
+  /*
+   * Single ATTRIBUTE filter — preferred over multiple AND-combined
+   * filters when the same attribute is being matched against an
+   * IN-list of values. One round trip, simpler shape.
+   */
+  "filter": {
+    "op": "ATTRIBUTE",
+    "expressions": [
+      /*
+       * `name=type, operator=IN, values=[…]` is the canonical
+       * "match by vertex type" pattern. The list here is the
+       * core set you care about on most tenants — extend if the
+       * tenant uses connector-specific types (CONNECTOR,
+       * ACN_CONFIG, etc.). Use `discovery_attribute_values
+       * (LAYER, "type")` to enumerate types that exist on a
+       * specific layer.
+       */
+      {
+        "name": "type",
+        "values": ["AGENT", "HOST", "DXI_SERVICE", "BUSINESSTRANSACTION", "INFERRED_DATABASE", "PRODUCT"],
+        "operator": "IN"
+      }
+    ]
+  },
+  "limit": 100,
+  "projection": "DETAILED"
+}

package/dist-node/02-discover-services.tas.data-store-tmd-eq264m6y.json

@@ -0,0 +1,4 @@
+{
+  "description": "Discovery: list major vertex types (AGENT, HOST, DXI_SERVICE, etc.) to understand the topology",
+  "tags": ["discovery", "tas"]
+}

package/dist-node/03-discover-sources.nassql-4tgp9jvv.md

@@ -0,0 +1,34 @@
+# 03-discover-sources (NASSQL)
+
+## Purpose
+
+Discover all metric source names and count how many metrics each source reports, ordered by metric count descending. This reveals which agents are producing the most metric data.
+
+## Query Construction
+
+Pipeline: `FROM_METADATA` (all metrics) -> `GROUP` by `metric.source` -> `COUNT` -> `ORDER` descending -> `KEEP` the two columns.
+
+Note: The column is `metric.source`, not `metric.sourceName`. The available columns from `FROM_METADATA` are revealed by the `DESCRIBE` operation (query 04) and are `metric.source` and `metric.path`.
+
+## API Surface Exercised
+
+- **FROM_METADATA**: Source operation that loads metric metadata
+- **GROUP**: Groups rows by one or more columns
+- **COUNT**: Aggregation that counts rows per group
+- **ORDER**: Sorts results by a column (with `sortDescending`)
+- **KEEP**: Selects which columns appear in the final output
+
+## Expected Output
+
+A tabular result where the header is `["metric.source", "metric_count"]` and each data row is a source name with its metric count. Ordered from highest to lowest.
+
+## What the Results Tell You
+
+Common high-volume metric producers (varies by tenant — exact counts depend on what's installed and what time window is being indexed):
+1. **OpenTelemetry sources** — frequently the largest single producer, especially for app/UI traffic (thousands of metrics)
+2. **Kubernetes agents** — node + pod + container metrics add up quickly
+3. **Infrastructure agents** — host-level CPU / memory / disk / network
+4. **Identity-provider agents** — authentication/session metrics
+5. **Synthetic-monitoring tools** — per-monitor latency + availability series
+
+Use this listing to identify which sources are worth targeting in subsequent NASSQL queries.

package/dist-node/03-discover-sources.nassql.data-store-by6sqk23.json5

@@ -0,0 +1,63 @@
+/*
+ * Discovery query #3 — rank metric sources by how many metrics each
+ * one publishes. Answers "who's noisy?" / "what's reporting most
+ * data?". Useful as a first NASSQL query against any tenant — gives
+ * you the menu of metric sources to choose from for follow-on FROM
+ * queries (datapoints) or `discovery_metrics` lookups.
+ *
+ * Pipeline shape: FROM_METADATA → GROUP → COUNT → ORDER → KEEP.
+ * Note `metric.source` is the column name (NOT `metric.sourceName`).
+ */
+{
+  "query": [
+    /*
+     * `FROM_METADATA` loads the metric METADATA catalog as rows
+     * (one row per metric definition). NOT to be confused with
+     * `FROM` which loads metric DATAPOINTS (values over time).
+     * For "how many metrics" / "what metrics exist", always
+     * FROM_METADATA. For "what was the value last hour", FROM.
+     */
+    {
+      "op": "FROM_METADATA",
+      "querySpecifier": { "op": "ALL" },
+      "alias": "all_metadata"
+    },
+    /*
+     * GROUP collapses rows by the named column(s). Here we group
+     * by `metric.source` so each output row is one source.
+     * GROUP MUST come before any aggregation (COUNT here).
+     */
+    {
+      "op": "GROUP",
+      "columns": ["metric.source"]
+    },
+    /*
+     * COUNT per group. `as: "metric_count"` names the new column
+     * — without `as`, you get a default name like `count` which
+     * is unfriendly downstream.
+     */
+    {
+      "op": "COUNT",
+      "as": "metric_count"
+    },
+    /*
+     * ORDER descending so the top noise sources are first.
+     * sortDescending is the per-column flag; you can mix asc/desc
+     * across multiple sort columns.
+     */
+    {
+      "op": "ORDER",
+      "columns": [{ "column": "metric_count", "sortDescending": true }]
+    },
+    /*
+     * KEEP must be the LAST op in a pipeline (server returns
+     * HTTP 400 if anything follows KEEP). It's the projection
+     * step — selects which columns the response includes.
+     */
+    {
+      "op": "KEEP",
+      "columns": ["metric.source", "metric_count"]
+    }
+  ],
+  "limit": 50
+}

package/dist-node/03-discover-sources.nassql.data-store-tmd-n3gy57wm.json

@@ -0,0 +1,4 @@
+{
+  "description": "Discovery: list distinct metric source names to understand what agents/hosts report data",
+  "tags": ["discovery", "nassql"]
+}

package/dist-node/04-discover-metadata-columns.nassql-vhzb0mrq.md

@@ -0,0 +1,26 @@
+# 04-discover-metadata-columns (NASSQL)
+
+## Purpose
+
+Use the `DESCRIBE` operation to reveal the column structure available from `FROM_METADATA`. This is essential before writing queries that reference specific column names.
+
+## Query Construction
+
+Simple two-step pipeline: `FROM_METADATA` (with `ALL` specifier) -> `DESCRIBE`. The `DESCRIBE` operation returns a single header row listing all available column names, with no data rows.
+
+## API Surface Exercised
+
+- **FROM_METADATA**: Source operation
+- **DESCRIBE**: Debug/introspection operation that outputs the column schema of the current result set
+
+## Expected Output
+
+A single-row result (just the header): `[["metric.source", "metric.path"]]`
+
+This tells us that `FROM_METADATA` with `ALL` produces two columns:
+- `metric.source` — the agent/source path (e.g., `SuperDomain|host|process|agent`)
+- `metric.path` — the metric attribute path (e.g., `GC Heap:Bytes In Use`)
+
+## What the Results Tell You
+
+When building NASSQL queries against metadata, you can only `GROUP`, `FILTER`, `KEEP`, or aggregate on `metric.source` and `metric.path`. Other columns (like `metric.id`, `metric.firstSeen`, `metric.lastSeen`) become available when using different specifiers or when joining with data.

package/dist-node/04-discover-metadata-columns.nassql.data-store-c9zr7p0q.json5

@@ -0,0 +1,35 @@
+/*
+ * Discovery query #4 — show the column shape of metric metadata
+ * results. `DESCRIBE` is the introspection op: feed it ANY pipeline
+ * stage's output and it returns the columns + types instead of the
+ * data. Reach for this when you're authoring a NASSQL pipeline and
+ * need to confirm what columns are available for downstream
+ * GROUP / FILTER / KEEP / etc.
+ *
+ * Pattern is identical for any source op: replace FROM_METADATA
+ * with FROM_TOPOLOGY (vertex columns) or FROM (datapoint columns)
+ * to introspect those.
+ */
+{
+  "query": [
+    /*
+     * Same FROM_METADATA-with-ALL-specifier pattern as #3 — load
+     * the full metric metadata catalog as rows.
+     */
+    {
+      "op": "FROM_METADATA",
+      "querySpecifier": { "op": "ALL" },
+      "alias": "metadata"
+    },
+    /*
+     * DESCRIBE replaces normal output with a column descriptor
+     * shape: one row per column, with `column.name` + `column.type`
+     * + sample values. Use as the ONLY downstream op (don't try
+     * to GROUP / FILTER after DESCRIBE — it's a terminal op).
+     */
+    {
+      "op": "DESCRIBE"
+    }
+  ],
+  "limit": 100
+}

package/dist-node/04-discover-metadata-columns.nassql.data-store-tmd-4ygrjvty.json

@@ -0,0 +1,4 @@
+{
+  "description": "Discovery: DESCRIBE the column structure of metric metadata results",
+  "tags": ["discovery", "nassql"]
+}

package/dist-node/10-filter-attribute-matches.tas-tafqmtw1.md

@@ -0,0 +1,33 @@
+# 10-filter-attribute-matches (TAS)
+
+## Purpose
+
+Demonstrate the `ATTRIBUTE` filter with the `MATCHES` (regex) operator to find vertices by pattern-matching on an attribute value.
+
+## Query Construction
+
+Uses `ATTRIBUTE` filter with `expressions` containing a single expression:
+- `name: "name"` — match against the vertex's `name` attribute
+- `operator: "MATCHES"` — regex match
+- `values: [".*tixchange.*"]` — Java-style regex (case insensitive via `caseInsensitive: true`)
+
+This finds any vertex whose name contains "tixchange" (the demo TixChange application).
+
+## API Surface Exercised
+
+- **Filter**: `ATTRIBUTE` with `MATCHES` operator
+- **AttributeExpression**: `name`, `values`, `operator`, `caseInsensitive`
+- **Projection**: `DETAILED`
+
+## Expected Output
+
+Returns up to 50 vertices related to the TixChange application, including:
+- `BUSINESSTRANSACTION` vertices (e.g., `/jtixchange_web/shop/checkout.shtml`)
+- `MYSQL_DB` vertices (e.g., `MYSQL_DB @ jtixchange`)
+- `INFERRED_DATABASE` vertices
+
+## What the Results Tell You
+
+The `MATCHES` operator performs Java regex matching against string attribute values. Unlike `IN` (exact match), `MATCHES` allows partial matching, wildcard patterns, and complex expressions. The `caseInsensitive` flag makes the regex case-insensitive.
+
+Note: The `expressions` field is an **array** of `AttributeExpression` objects. Each expression specifies a `name` (attribute name), `values` (patterns to match), and `operator`.

package/dist-node/10-filter-attribute-matches.tas.data-store-tmd-m2sendv0.json

@@ -0,0 +1,4 @@
+{
+  "description": "ATTRIBUTE filter with MATCHES operator: regex search for vertices with 'tixchange' in their name",
+  "tags": ["tas", "filter", "attribute"]
+}

package/dist-node/10-filter-attribute-matches.tas.data-store-whdc6vbc.json5

@@ -0,0 +1,35 @@
+/*
+ * `ATTRIBUTE` filter with the `MATCHES` operator — Java-style regex
+ * against an attribute value. Use when an exact value isn't known
+ * but a pattern is (substring search, prefix match, etc.).
+ *
+ * Default to `caseInsensitive: true` for human-input substrings;
+ * default to `false` for tenant-internal identifiers (those are
+ * usually case-sensitive). MATCHES is more expensive than IN — if
+ * you have an enumerable value list, prefer IN.
+ */
+{
+  "filter": {
+    "op": "ATTRIBUTE",
+    "expressions": [
+      /*
+       * `name` is the attribute being matched. `name` (the
+       * attribute) and `name` (the field) collide here — easy
+       * to misread. The OUTER `name: "name"` selects the vertex's
+       * `name` attribute as the target.
+       *
+       * `MATCHES` takes a Java-flavoured regex. Wildcards: `.*`
+       * for any-chars; anchors are NOT implicit (the regex matches
+       * anywhere unless you anchor with `^` or `$`).
+       */
+      {
+        "name": "name",
+        "values": [".*tixchange.*"],
+        "operator": "MATCHES",
+        "caseInsensitive": true
+      }
+    ]
+  },
+  "limit": 50,
+  "projection": "DETAILED"
+}

package/dist-node/11-filter-and-compose.tas-m8856738.md

@@ -0,0 +1,29 @@
+# 11-filter-and-compose (TAS)
+
+## Purpose
+
+Demonstrate the `AND` boolean filter to compose two `ATTRIBUTE` filters: restricting by vertex type AND by exact name.
+
+## Query Construction
+
+Uses `AND` with `input` (array of sub-filters):
+1. `ATTRIBUTE` with `type IN ["BUSINESSTRANSACTION"]` — only business transaction vertices
+2. `ATTRIBUTE` with `name IN ["/jtixchange_web/shop/checkout.shtml", "/jtixchange_web/shop/signon.shtml"]` — exact name match for two specific BT URLs
+
+Both conditions must be true for a vertex to be included.
+
+## API Surface Exercised
+
+- **Filter**: `AND` with `input` array
+- **Filter**: `ATTRIBUTE` with `IN` operator (exact value matching)
+- **Composition**: Two filters combined with boolean AND
+
+## Expected Output
+
+Returns 4 vertices (there are duplicate BTs across different agent connections) and 16 edges connecting them to related entities. The AND filter ensures only vertices that are both BUSINESSTRANSACTION type AND have one of the two specified names are returned.
+
+## What the Results Tell You
+
+The `AND` filter uses `input` (array), not `filters`. Each sub-filter is a complete filter object. The API returns matching vertices along with their directly connected edges by default (the edge inclusion is implicit for BT vertices connected to other topology entities).
+
+Key learning: On this tenant, BT names include the full URL path (e.g., `/jtixchange_web/shop/checkout.shtml`), so `IN` requires exact matches including leading slashes.

package/dist-node/11-filter-and-compose.tas.data-store-dh5meyk8.json5

@@ -0,0 +1,56 @@
+/*
+ * Compose two ATTRIBUTE filters with AND — restrict results to
+ * vertices that satisfy BOTH. Demonstrates the standard "narrow by
+ * type, then narrow by name" pattern that 80% of investigative
+ * TAS queries follow.
+ *
+ * Could be authored as a single ATTRIBUTE op with two expressions
+ * in the array (also AND-combined), but the two-op form is more
+ * legible when the constraints are conceptually distinct + makes
+ * each constraint independently editable in the ui.
+ */
+{
+  /*
+   * AND: ALL children must match. NEVER author empty AND/OR
+   * arrays — the server returns HTTP 400. Min 1 child.
+   */
+  "filter": {
+    "op": "AND",
+    "input": [
+      /*
+       * First narrowing: type. Always cheaper to filter by type
+       * before name — the type index is more selective.
+       */
+      {
+        "op": "ATTRIBUTE",
+        "expressions": [
+          {
+            "name": "type",
+            "values": ["BUSINESSTRANSACTION"],
+            "operator": "IN"
+          }
+        ]
+      },
+      /*
+       * Second narrowing: exact name match against a small list.
+       * Use IN with explicit values when you know the exact
+       * targets — far more efficient than MATCHES with a regex.
+       *
+       * Note these particular names include the leading slash
+       * and the .shtml extension — exact match is byte-for-byte.
+       */
+      {
+        "op": "ATTRIBUTE",
+        "expressions": [
+          {
+            "name": "name",
+            "values": ["/jtixchange_web/shop/checkout.shtml", "/jtixchange_web/shop/signon.shtml"],
+            "operator": "IN"
+          }
+        ]
+      }
+    ]
+  },
+  "limit": 20,
+  "projection": "DETAILED"
+}

package/dist-node/11-filter-and-compose.tas.data-store-tmd-mfn8a16f.json

@@ -0,0 +1,4 @@
+{
+  "description": "AND filter: combine type=BUSINESSTRANSACTION with exact name IN for checkout and signon BTs",
+  "tags": ["tas", "filter", "boolean"]
+}

package/dist-node/12-filter-or-not.tas-21zab96s.md

@@ -0,0 +1,35 @@
+# 12-filter-or-not (TAS)
+
+## Purpose
+
+Demonstrate complex boolean composition with `OR`, `AND`, and `NOT` filters nested together.
+
+## Query Construction
+
+The filter says: "give me all k8s pods OR agents that are NOT Logstash agents."
+
+```
+OR
+├── ATTRIBUTE(type IN [k8s_POD])
+└── AND
+    ├── ATTRIBUTE(type IN [AGENT])
+    └── NOT
+        └── ATTRIBUTE(name MATCHES [.*Logstash.*])
+```
+
+This exercises three levels of boolean nesting.
+
+## API Surface Exercised
+
+- **Filter**: `OR` with `input` array
+- **Filter**: `AND` with `input` array (nested inside OR)
+- **Filter**: `NOT` with single `input` filter (nested inside AND)
+- **Filter**: `ATTRIBUTE` with both `IN` and `MATCHES` operators
+
+## Expected Output
+
+Returns ~50 vertices: a mix of k8s_POD vertices and AGENT vertices, with any agent whose name matches "Logstash" excluded. On a typical tenant the result will be Kubernetes / Infrastructure / Prometheus / MySQL-style agents alongside the pods — minus whatever Logstash-named agents (if any) the tenant happens to run.
+
+## What the Results Tell You
+
+Boolean filters can be arbitrarily nested. `NOT` takes a single `input` filter (not an array). `OR` and `AND` take an `input` array. This pattern is useful for building complex exclusion rules in topology queries.

package/dist-node/12-filter-or-not.tas.data-store-7vjr4fnd.json5

@@ -0,0 +1,83 @@
+/*
+ * Three-level boolean composition: OR(k8s_POD, AND(AGENT, NOT(name
+ * MATCHES /Logstash/))). Demonstrates how AND / OR / NOT compose
+ * arbitrarily — they're all just filters that take filter children.
+ *
+ * NOT takes a SINGLE `input` filter (not an array, unlike AND/OR).
+ * Easy to mis-author as `input: [...]` — produces validation error.
+ *
+ * When NOT's child is a MATCHES expression, the result is "everything
+ * that does NOT match this regex." Note that this is far more
+ * expensive than NOT_MATCHES on the inner ATTRIBUTE expression — if
+ * you're just inverting a single MATCHES, prefer the operator-level
+ * inversion. NOT(...) wrapped is for inverting multi-expression /
+ * compound filters.
+ */
+{
+  /*
+   * OR: ANY child matches. Like AND, must have ≥1 child.
+   */
+  "filter": {
+    "op": "OR",
+    "input": [
+      /*
+       * Branch A — straightforward type filter.
+       */
+      {
+        "op": "ATTRIBUTE",
+        "expressions": [
+          {
+            "name": "type",
+            "values": ["k8s_POD"],
+            "operator": "IN"
+          }
+        ]
+      },
+      /*
+       * Branch B — AGENTs whose name does NOT match Logstash.
+       * Compound: AND(AGENT-type, NOT(name-matches-Logstash)).
+       */
+      {
+        "op": "AND",
+        "input": [
+          {
+            "op": "ATTRIBUTE",
+            "expressions": [
+              {
+                "name": "type",
+                "values": ["AGENT"],
+                "operator": "IN"
+              }
+            ]
+          },
+          /*
+           * NOT takes `input` as a SINGLE filter (not an array).
+           * `input: { op: ... }`, NOT `input: [{ op: ... }]`.
+           * Common mis-authoring trap.
+           *
+           * Could be rewritten as NOT_MATCHES on the ATTRIBUTE
+           * expression directly — cheaper. NOT-wrapping is for
+           * cases where the inner filter is multi-expression or
+           * itself compound.
+           */
+          {
+            "op": "NOT",
+            "input": {
+              "op": "ATTRIBUTE",
+              "expressions": [
+                {
+                  "name": "name",
+                  "values": [".*Logstash.*"],
+                  "operator": "MATCHES",
+                  "caseInsensitive": true
+                }
+              ]
+            }
+          }
+        ]
+      }
+    ]
+  },
+  "limit": 50,
+  "projection": "DETAILED"
+}

package/dist-node/12-filter-or-not.tas.data-store-tmd-am9smwe5.json

@@ -0,0 +1,4 @@
+{
+  "description": "OR + AND + NOT composition: all k8s pods OR (agents NOT matching 'Logstash')",
+  "tags": ["tas", "filter", "boolean"]
+}