@dx-do/cli 5.2.49 → 5.2.50

package/dist-node/entity-relationships-cevz61kj.md

@@ -0,0 +1,142 @@
+---
+id: entity-relationships
+title: Entity relationships — five kinds, knowing which is in play
+applies_to: all
+tags: [reference, authoring]
+related: [investigation-planning, service-hierarchies, universes-and-scopes, metrics-grounding]
+---
+
+# Entity relationships
+
+DXO2 has multiple, overlapping ways for two entities to be related. Most user questions about "X and Y" implicitly want one of these — but it's not always the same one. This cookbook enumerates the five kinds and how to use each.
+
+## 1. TAS edges (the actual graph)
+
+Edges between vertices are the most concrete relationship: directed, attribute-bearing, queryable via TAS `TRAVERSE`. Each edge has a `semantic` attribute that hints at the kind of relationship.
+
+**The semantics observed on real tenants** (from a survey of 6,513 edges):
+
+| `semantic` | Count | Meaning |
+|---|---|---|
+| `contains` | ~50% | Structural containment (cluster contains namespace contains deployment, host contains process, etc.) |
+| `agent-monitors` | ~22% | The AGENT on the source side observes the entity on the target side |
+| (no semantic) | ~17% | A non-trivial fraction of edges have NO `semantic` attribute |
+| `composed_of` | ~4% | Compositional (deployment composed of replicaset, service composed of pods) |
+| `runs_on` | ~4% | Runtime placement (pod runs on node) |
+| `orchestrates` | small | Workload-controller relationships in k8s |
+| `declares`, `consists_of` | small | Less-common variants of containment |
+| `Related To` | small | Loose / generic — tenant-specific |
+| `collectsData`, `isConnectedL2`, `isadjacentto` | small | Integration-specific |
+
+**The 17% unlabeled edges matter.** Filtering by `semantic` will *miss* them. Default to NOT filtering by semantic unless you're sure the data you want has it.
+
+### Where TAS edges come from
+
+Four mechanisms produce edges:
+
+1. **Single-agent multi-entity emission** — an agent that monitors several entities at once also emits the edges between them (e.g. the k8s agent emits the entire pod/deployment/namespace tree).
+2. **Agent correlation telemetry** — an APM agent watching app-to-app calls emits backend-call edges.
+3. **Platform-side inference rules** — the platform deduces edges from attribute patterns (e.g. matching IP addresses, matching `applicationName`).
+4. **Manual / integration imports** — NetOps integrations produce their own edge structure.
+
+Different mechanisms give different reliability. Inferred edges are sometimes brittle.
+
+### Authoring against TAS edges
+
+```js
+// Find what depends on X (outgoing edges from X)
+{ "filter": { "op": "AND", "input": [
+    { "op": "ATTRIBUTE", "expressions": [{ "name": "name", "values": ["X"], "operator": "EQ" }] },
+    { "op": "TRAVERSE", "depth": 1, "direction": "OUTBOUND" }
+] }, "limit": 50 }
+```
+
+Use `direction: "INBOUND"` for "what does X belong to" and `"BIDIRECTIONAL"` when you don't know which side you're on.
+
+## 2. Service membership (DXO2 services)
+
+Two entities can be members of the same DXO2 service even when no edge connects them directly. Service membership is an organizational relationship layered over the topology.
+
+- **Same service, no edge** → likely related (the customer chose to group them).
+- **Parent service** → child entities are part of a larger logical unit.
+- **Sibling services** → loosely related; sometimes via parent dependency.
+- **Niece / nephew (children of sibling services)** → the loosest meaningful tie.
+
+Service-level mechanics live in `cookbooks/service-hierarchies`. Use the `service-dependency-graph` API for the runtime view of inter-service dependencies.
+
+### The `serviceNames` shortcut
+
+The platform indexes service membership directly on each entity via a **`serviceNames`** attribute — an array like `["NA_Billing", "NA_Provisioning"]`. It's kept current automatically (typically within ~1 min of entity creation, ~2 min of new-service creation), so it's a reliable, **single-query** answer to "what services does this entity belong to" — far faster than a hierarchy walk.
+
+**Gotcha**: the attribute is **not in the default projection**. Pass `includeServices: true` on the TAS query envelope and `serviceNames` shows up in `vertex.attributes`. Without the flag, the field is silently absent and an agent will incorrectly conclude the entity has no service membership.
+
+```json
+{
+  "filter": { "op": "ATTRIBUTE", "expressions": [{ "name": "name", "values": ["host-001"], "operator": "EQ" }] },
+  "limit": 5,
+  "projection": "DETAILED",
+  "includeServices": true
+}
+```
+
+The companion flag is `includeStatus: true`, which surfaces the `state` / `status` attribute (similarly omitted by default). Set both when you want a single-shot "identity + service membership + health" snapshot. See `entities/service` for the full pattern.
+
+A common analysis pattern:
+
+1. User asks about entity X.
+2. Find the service(s) X belongs to — **read X's `serviceNames` (with `includeServices: true`)**, don't walk the hierarchy.
+3. Pull other members of those services for "things related to X" — `op: SERVICE` filter.
+4. Walk parent and dependent services for the broader picture.
+
+## 3. Universe membership (APM Universe vs O2 Universe)
+
+Two entities in the same universe are in the same **scope**. They aren't necessarily related — universe is a coarser axis than service — but the universe boundary is meaningful when answering "what's nearby":
+
+- **APM Universe** typically contains telemetry sources and the entities they produce.
+- **O2 Universe** typically contains platform-side and integration-imported data.
+
+When a user asks "where is X" or "what universe is X in", the answer is one of two universe kinds. See `lexicon/universe` and `cookbooks/universes-and-scopes`.
+
+## 4. Attribute similarity
+
+Two entities sharing an IP address, hostname, or FQDN value are almost always related, even if no edge connects them. This is the canonical pattern when:
+
+- **`HOST` and `Host` for the same physical machine** — APM and NetOps records of the same box. No edge between them. Match on `acnHostName`, `acnOtherHostNames`, `dx_hostname_list`, `NetworkAddress`, IP attributes.
+- **Source/destination IP pairs in network metrics** — different attribute names, same IP value, different vertices.
+- **An AGENT and the HOST it runs on** — usually edge-connected, but the `SystemFQHostName` attribute on the AGENT directly names the host even without traversal.
+
+Authoring pattern:
+
+1. Collect candidate identity attributes for each entity (use the entity catalog's `typical_attributes` field — see `entities/catalog.json5`).
+2. For each candidate attribute, query for other entities with a similar value.
+3. Cross-reference matches with their types — a match between a `HOST` and a `k8s_NODE` of the same hostname is high-signal; a match between two unrelated `Host_Device`s with the same vendor model number is noise.
+
+## 5. Metric-name- and metric-value-implied
+
+Sometimes the relationship is hidden inside the **metric data itself**, not in the topology graph:
+
+- A metric named `JDBC_Pool|<host>|<pool>:Active Connections` implies a connection-pool resource at that host. There's no `JDBC_CONNECTION_POOL` vertex — the resource exists only in the metric path.
+- A metric VALUE can be a string. `queue_name=queue://host/queuename` reveals which queue host is in use.
+- Some agents put resource identity in path segments; some put it in metric values; both can be the only signal.
+
+This is the **metric-first** investigation strategy. See `cookbooks/metrics-grounding`. If a metric pattern recurs, an inventorize rule can materialize the implied resource as a vertex (`lexicon/inventorize`).
+
+## Picking the right kind to ask
+
+When a user asks about "the X that A uses" / "what's related to A":
+
+1. **Try TAS edges first** when both endpoints are likely vertices and the relationship is explicit (call graph, containment).
+2. **Service membership** when the user is asking about organizational closeness.
+3. **Universe membership** for "is it even in scope" questions.
+4. **Attribute similarity** when bridging integrations (APM ↔ NetOps, k8s ↔ infra agent on the same node).
+5. **Metric-implied** when the resource genuinely has no vertex (JMX-style).
+
+Most real questions touch more than one kind. The rule of thumb: **start with the most explicit kind that could plausibly answer**, fall back to broader/looser kinds if it doesn't.
+
+## See also
+
+- `cookbooks/investigation-planning` — the planning loop that uses this taxonomy.
+- `cookbooks/service-hierarchies` — service membership in depth.
+- `cookbooks/universes-and-scopes` — universe membership in depth.
+- `cookbooks/metrics-grounding` — the metric-implied case.
+- `cookbooks/tas-cookbook` — TAS TRAVERSE syntax and operators.

package/dist-node/gotchas-8ab64kcd.md

@@ -0,0 +1,389 @@
+---
+id: gotchas
+title: Empirical gotchas — things the schema docs alone don't tell you
+applies_to: all
+tags: [reference, validation]
+related: [tas-quickstart, nassql-quickstart, mm-quickstart]
+---
+
+# Gotchas
+
+A list of behaviors that tripped up real query authoring (human or agent).
+Each entry includes the symptom, the cause, and how the schema guards
+against it (where possible).
+
+These are **bundled, universal** gotchas — behaviors of the DXO2 server
+that every customer encounters. They ship with each release.
+
+**Capturing your own findings**: when you discover a behavior specific
+to *your* tenant (or a recipe that worked for you), leave the reasoning
+in the **JSON5 description** on the relevant op or at the query top-level.
+Agents reading your query via `get_query` get that context for free, and
+it round-trips into the file as a `/* */` block comment. Tenant-specific
+knowledge belongs on the queries themselves.
+
+If you find a gotcha that applies to *every* customer, that's a candidate
+for inclusion here — file an issue or PR against `packages/corpus/cookbooks/`
+in the dx-do source repo.
+
+---
+
+## TAS — empty AND / OR rejected by server
+
+**Symptom**: `400 Bad Request` from `/tas/graph/query`.
+**Cause**: `{"op":"AND","input":[]}` is semantically meaningless (empty
+boolean composite). Server rejects.
+**Schema guard**: `TasAndFilterSchema.input` and `TasOrFilterSchema.input`
+have `.min(1)` — caught at SPA validation before submit.
+
+---
+
+## NASSQL — empty FILTER AND / OR rejected
+
+**Symptom**: same as above — server 400.
+**Cause**: `{"op":"AND","spec":[]}` inside a `FILTER` predicate.
+**Schema guard**: `QueryFilterAndSpecSchema.spec` and `QueryFilterOrSpecSchema.spec`
+have `.min(1)`.
+
+---
+
+## NASSQL — GROUP / ORDER / KEEP cannot be empty
+
+**Symptom**: server 400 or noop.
+**Cause**: `{"op":"GROUP","columns":[]}` has no grouping key, etc.
+**Schema guard**: All three ops' `columns` field has `.min(1)`.
+
+---
+
+## MM — `ID` specifier requires non-empty `ids`
+
+**Symptom**: `400 Bad Request` from MM endpoint.
+**Cause**: `{"op":"ID"}` or `{"op":"ID","ids":[]}` — server requires
+explicit IDs.
+**Schema guard**: `QueryIdSpecifierSchema.ids` has `.min(1)`. Read IDs
+from a previous MM query's leftmost result column, or pass them
+explicitly when chaining queries.
+
+---
+
+## MM — empty AND / OR specifier rejected (4 levels deep)
+
+**Symptom**: server 400.
+**Cause**: Same pattern as TAS / NASSQL but applies at all four MM tree
+levels (top-level, source-name, folder-name, attribute-name). Empty
+boolean composites are always wrong.
+**Schema guard**: All eight `*AndSpecifierSchema` / `*OrSpecifierSchema`
+variants have `.min(1)` on `specifiers`.
+
+---
+
+## NASSQL FROM_TOPOLOGY — querySpecifier ignores most fields
+
+**Symptom**: top-level `limit` / `projection` / `time` set on
+`FROM_TOPOLOGY.querySpecifier` either silently drop or 400.
+**Cause**: Although the field types as `TasQuerySchema` (full envelope),
+the server only honors `filter`. Pipeline-level `limit` (on the top-level
+`QueryRequest`) is what caps row count.
+**Workaround**: don't put `limit`, `projection`, `time` etc. inside
+`querySpecifier`. Author the TAS filter directly; place row-capping on
+the outer NASSQL envelope.
+**Schema guard**: documented in JSDoc on `QueryFromTopologySpecSchema` and
+`TasQuerySchema`.
+
+---
+
+## NASSQL JOIN_TOPOLOGY — no querySpecifier exists
+
+**Symptom**: agents try to add `querySpecifier` to JOIN_TOPOLOGY and
+the schema rejects.
+**Cause**: Unlike FROM_TOPOLOGY, JOIN_TOPOLOGY has no specifier field.
+The topology context is inherited from the upstream pipeline data via
+`externalIdColumn`.
+**Workaround**: to constrain the topology side of a join, do a separate
+FROM_TOPOLOGY into an aliased branch and JOIN against that branch.
+**Schema guard**: documented in JSDoc on `QueryJoinTopologySpecSchema`.
+
+---
+
+## MM — unbounded ALL queries return tens of MB
+
+**Symptom**: queries with `{"specifier":{"op":"ALL"}}` and no `clamp`
+return huge responses, sometimes crashing browser tabs.
+**Cause**: server returns ALL matching metrics by default.
+**Workaround**: always set `clamp: 500` (or a similar bound) for new
+specifiers. Raise only if needed.
+**Schema guard**: documented in JSDoc on `MetadataMetricQuerySchema`. New
+MM queries created via `create_query` default `clamp: 500`.
+
+---
+
+## TAS — ATTRIBUTE without a `layer` matches across all layers
+
+**Symptom**: results include unexpected vertex types.
+**Cause**: TAS attributes are layer-scoped. `{"op":"ATTRIBUTE",
+"expressions":[{"name":"hostname",...}]}` without a `layer` matches
+hostname-bearing attributes on every layer that has them.
+**Workaround**: set `ATTRIBUTE.layer` to scope the match. The op-level
+`layer` is inherited into each expression row's `layer` field unless
+overridden explicitly per-expression.
+**Schema guard**: none — empty `layer` is valid and intentional in some
+queries (cross-layer search).
+
+---
+
+## NASSQL — pipeline ordering matters
+
+**Symptom**: `WINDOW` / `GROUP` / aggregation sequence produces wrong
+results or fails validation.
+**Cause**: NASSQL ops don't reorder themselves. `GROUP` before `WINDOW`
+behaves differently from `WINDOW` before `GROUP`.
+**Workaround**: standard ordering is `FROM* → FILTER → WINDOW → GROUP →
+AGG → ORDER → KEEP`. Use `run_partial_query` with `upToStep: N` to
+verify after each insertion.
+**Schema guard**: none — the schema is order-agnostic, the runtime is not.
+
+---
+
+## Discovery — `discovery_metrics` is capped at 1000 names
+
+**Symptom**: agents can't find a metric they know exists on a large tenant.
+**Cause**: `getMetricsHandler` caps the unique name list at 1000 to
+keep the response payload reasonable.
+**Workaround**: if you know the metric ID, use `ID` specifier directly
+without depending on the discovery cache.
+**Schema guard**: documented in `getMetricsHandler` JSDoc.
+
+---
+
+## `create_query` — `shortName` is prefixed with an auto-numbered bucket
+
+**Symptom**: agent passes `shortName: "all-hosts"` to `create_query` and the saved query's id comes back as `15-all-hosts` (or some other small integer).
+**Cause**: `create_query` auto-assigns a numeric prefix per query-type bucket — the next free integer in `~/.dxdo/queries/<alias>/` for queries of the same type. Allows stable sorting and visual ordering in any tool that lists the saved queries.
+**Workaround**: nothing to do — this is by design. When chaining `create_query` → `get_query` / `update_query` / `signal_handoff_to_ui`, use the RETURNED `id` (which includes the prefix), NOT the `shortName` you passed in. Pre-assigning your own prefix via the `prefix` argument bypasses the bucket counter.
+**Schema guard**: documented in `create_query` tool description; the response body always includes the assigned id.
+
+---
+
+## NASSQL — `metric.source` REGEX needs the `<domain>|` prefix
+
+**Symptom**: a NASSQL `FROM` query with a `sourceNameSpecifier` REGEX like `.*<host-name>.*` returns zero rows even though the host clearly exists and is reporting metrics.
+**Cause**: `metric.source` strings are pipe-delimited multi-segment values shaped `<domain>|<host>|<bus>|<role>` (e.g. `SuperDomain|host-001|Infrastructure|Agent`). The naive `.*<host>.*` pattern doesn't account for the `<domain>|` prefix or the literal `|` separators (which are regex meta-characters needing escape). A pattern that *looks* like it should match doesn't.
+**Workaround**: see `cookbooks/metric-source-names` for the full shape + canonical regex patterns + the empirical-discovery move (`run_partial_query` with `FROM_METADATA upToStep:0` to inspect actual source values before authoring the FROM regex).
+**Schema guard**: none — the regex is opaque to schema validation; empty results are silent.
+
+## NASSQL — verify a FROM is matching anything before pulling on the whole pipeline
+
+**Symptom**: a NASSQL query runs end-to-end but produces nulls or
+zero rows in unexpected places — most often after an aggregator over
+multiple FROMs where one of them silently matches no metric. The
+end-to-end result is "valid but empty" with no error message pointing
+at which FROM is the empty branch.
+
+**Diagnostic**: run each FROM (or FROM_METADATA) **in isolation** as a
+two-step pipeline:
+
+```json
+{
+  "query": [
+    { "op": "FROM", "querySpecifier": <THE_SPECIFIER>, "alias": "probe" },
+    { "op": "KEEP", "columns": ["metric.id"] }
+  ],
+  "limit": 50
+}
+```
+
+The result is `[["metric.id"], <id1>, <id2>, …]`. Zero data rows means
+the specifier matches nothing in this tenant. Common causes:
+
+- An `ATTRIBUTE` predicate inside `attributeNameSpecifier` that filters
+  by a value the tenant doesn't actually store in that form (e.g.
+  `is_Custom_health IN ["true"]` when the tenant stores it as a boolean
+  type, not the string `"true"`).
+- A REGEX `pattern` that doesn't match any actual `metric.path` /
+  `metric.source`.
+- A `sourceNameSpecifier` `EXACT` name that's stale or misspelled.
+
+**Refining the filter**: relax the predicates one at a time
+(start by removing the `ATTRIBUTE` predicate while keeping the
+REGEX) and re-run the isolation pipeline. When rows come back, sample
+a few `metric.id` values, look up their attributes via Metrics-Metadata,
+and see how the filter you originally wanted should be expressed against
+the tenant's actual data shape.
+
+**Tooling**: the data-store visual editor surfaces a "Run JUST this
+step" control on `FROM` / `FROM_METADATA` headers that runs the
+two-step probe above and shows the result in the Debug pane — same
+diagnostic, no JSON5 editing required.
+
+**Schema guard**: none — empty results are always valid; the server has
+no way to tell that empty wasn't intended.
+
+---
+
+## NASSQL — `GROUP` only drops non-grouped columns when followed by an aggregator
+
+**Symptom**: a `GROUP` step appears to have done nothing — non-grouped
+columns are still present in the output of the next step (verified via
+`DESCRIBE` or by running partial up-to-this-step).
+
+**Cause**: `GROUP` itself doesn't immediately prune the column set. It
+registers the grouping key for the *next aggregator* in the pipeline:
+
+- `GROUP → AGG` / `→ COUNT` / `→ SUM` / `→ MEAN` / `→ MIN` / `→ MAX`
+  / `→ FIRST` / `→ LAST` / `→ QUANTILE` / `→ NASS_AGG` → output
+  collapses to *grouping key columns* + each aggregator's `as` outputs;
+  every other column is dropped here.
+- `GROUP → BOTTOM` / `→ TOP` / `→ ORDER` / `→ KEEP` / `→ FILTER` (no
+  aggregator between) → upstream columns survive unchanged. `GROUP` has
+  no row-level effect; it only registered a key that would have applied
+  if an aggregator had followed.
+
+**Workaround / authoring rule**: if you need column-pruning behavior
+without an aggregator, follow `GROUP` with `KEEP` instead. If you need
+the per-group reduction, ensure an aggregator is in the pipeline
+between `GROUP` and any `KEEP` / output projection. Running partial
+up-to-this-step on the first column-input field after `GROUP` is the
+fastest way to verify which column shape you actually have at that
+boundary.
+
+**Repeated GROUP overrides** the previous user-grouping key — useful
+when you want to GROUP-aggregate-then-GROUP-aggregate again on a
+different key.
+
+**Schema guard**: none — both flows are server-valid; surprise comes
+from the column shape, not from a hard error.
+
+---
+
+## NASSQL — `alias` does NOT prefix output column names
+
+**Symptom**: a `FROM` step with `alias: "health"` is documented to namespace
+its output columns as `health.data.value` / `health.metric.source` / etc.,
+but running the pipeline up to that step and inspecting `rows[0]` shows the
+columns are still flat — `data.value`, `metric.source`, `metric.path`. The
+prefixed name (`health.data.value`) doesn't appear on any row, so a
+downstream `KEEP { columns: ["health.data.value"] }` returns nothing.
+
+**Cause**: aliases are a **logical reference scope** consumed by downstream
+ops that resolve them at execution time (AGG / SCRIPT / FILTER expressions
+correctly understand `health.data.value`), but the runtime never rewrites
+the row-level column keys with the alias prefix. The canonical schema's
+`.describe()` text on `alias` is misleading — what aliases actually do is
+let multiple FROMs (or JOIN_DATA / JOIN_METADATA) share a column-name
+namespace internally without colliding when the engine merges their row
+sets.
+
+**Workaround**:
+
+1. **Reference aliased columns in expressions, not in projections.** AGG's
+   inner `column`, FILTER predicates, MAP `fn`, SCRIPT `inputColumns[]`,
+   etc. all resolve `<alias>.<col>` correctly.
+2. **Project the bare column names in `KEEP`.** `KEEP { columns: ["data.value", "metric.source"] }`
+   works; `KEEP { columns: ["health.data.value"] }` returns empty.
+3. **If you need to disambiguate two FROMs that emit the same column
+   name in the final result**, use `KEEP`'s positional `as[]` to rename:
+   `KEEP { columns: ["data.value", "data.value"], as: ["health_value", "custom_value"] }`.
+
+**Schema guard**: none — the `alias` field's `.describe()` text is the
+trap. Tooling that suggests column names should NOT include
+`<alias>.<col>` variants in the suggestion list at the row level; only
+expression contexts (AGG / FILTER / SCRIPT / MAP) accept them.
+
+---
+
+## TAS — `STATUS.statusFilter`'s `STATE` op is currently a server-side no-op
+
+**Symptom**: a TAS query of the shape
+```json
+{ "op": "STATUS", "input": filter,
+  "statusFilter": { "op": "STATE", "state": [4] } }
+```
+returns zero vertices even when vertices with the requested numeric status
+demonstrably exist (verified by running `input` alone with `includeStatus: true`
+and reading `states[].status` from the response). Worse: setting `not: true`
+returns *every* input vertex regardless of what's in `state[]` — `not` flips
+an empty match-set to the universal set, masking the underlying breakage.
+
+**Cause**: the server-side handler doesn't bind the `STATE` op's `state[]`
+array. The predicate is effectively a no-op. Other leaf ops in the same
+state-filter union (`ALERT`, `METRIC`, `VERTEX_ID`, `NAMESPACE`,
+`MANAGEMENT_MODULE`) appear to work — only `STATE` is affected.
+
+**Numeric status reference** (values appearing in `states[].status`):
+
+| `status` | Label |
+|---|---|
+| 0 | UNKNOWN |
+| 1 | OK |
+| 2 | MINOR |
+| 3 | MAJOR |
+| 4 | CRITICAL |
+
+The rolled-up per-vertex severity (the value the platform UI shows on the
+status badge) lives on the state row whose `stateExternalId.alert` is
+`"sa://sa_status"` — a synthetic aggregate alert that summarizes all of a
+vertex's individual alerts and metrics. Per-alert / per-metric rows report
+their own `status` independently and can disagree with the rollup.
+
+**Workaround — split into two queries and filter client-side.** Example
+goal: *for each HOST currently CRITICAL, list any downstream databases
+whose status is not OK.*
+
+1. **Pull candidates with state attached.** Run the source-side topology
+   query with `includeStatus: true`. From `states[]`, keep only rows where
+   `stateExternalId.alert === "sa://sa_status"`, group by `vertexId`, and
+   read `status`. Collect the matching vertices' `externalId` values.
+
+   ```json
+   {
+     "limit": 5000,
+     "includeStatus": true,
+     "filter": {
+       "op": "ATTRIBUTE",
+       "expressions": [
+         { "name": "type", "operator": "IN", "values": ["HOST"] }
+       ]
+     }
+   }
+   ```
+
+   Client-side: keep `externalId`s where the rollup row's `status === 4`.
+
+2. **Pin those externalIds and traverse.** Issue a second query whose
+   filter is `VERTEX(externalId: [...])` → `TRAVERSE` (or `FOLLOW_PATH`)
+   to the target type, again with `includeStatus: true` so the downstream
+   side can be filtered on the client.
+
+   ```json
+   {
+     "limit": 5000,
+     "includeStatus": true,
+     "filter": {
+       "op": "TRAVERSE",
+       "input": { "op": "VERTEX", "externalId": ["<id-1>", "<id-2>"] },
+       "traverse": [{ "direction": "ANY", "repeat": 3 }]
+     }
+   }
+   ```
+
+   Then client-side: keep vertices whose `type` is the target (e.g.
+   database) and whose rollup `states[].status !== 1` (not OK).
+
+The rest of `STATUS` is fine — `ALERT(alertId)`, `METRIC(metricId)`,
+`NAMESPACE`, and `MANAGEMENT_MODULE` predicates all narrow as documented.
+Avoid `STATE` until this is resolved.
+
+**Schema guard**: none — the server silently accepts the `state[]` field
+and returns empty (or, with `not: true`, universal) results without a
+validation error. Tools that surface the `STATE` op in a form-style
+editor still produce wire-valid JSON, but it won't take effect until the
+platform handler is fixed.
+
+---
+
+## `run_query` — empty payload silently dumps the whole topology
+
+**Symptom**: `run_query({type: "tas", payload: {}})` (no filter, no limit) returns a response that looks innocuous in the wire but represents megabytes of topology data.
+**Cause**: `{}` parses as a valid TAS payload — `filter` defaulting to no-filter is equivalent to `{op:"ALL"}`, and `limit` defaults to "no limit." Returns the entire bound tenant's topology. On large tenants that's 10MB+ + may be saved to disk by ui rather than returned inline. The same trap exists in NASSQL (`FROM_METADATA / FROM_TOPOLOGY / FROM` with `op:"ALL"` and no row-reducing op + no top-level `limit`) and in Metrics Metadata (`specifier: {op:"ALL"}` or specifier missing, `clamp` unset).
+**Workaround**: NEVER author a `run_query` payload that scans everything without scoping. For TAS, pair every `op:"ALL"` filter with a sane `limit` (5–100 for sampling). For NASSQL, either narrow the source op's specifier (`SPEC` + `sourceNameSpecifier` / `attributeNameSpecifier`; or a TAS filter for `FROM_TOPOLOGY`), include an aggregation (GROUP+COUNT, TOP/BOTTOM, FILTER), or set top-level `limit`. For MM, narrow the specifier or pass a sane `clamp`. See `corpus_get('queries', '01-discover-vertices')` and `corpus_get('queries', '03-discover-sources')` for canonical bounded-discovery patterns.
+**Schema guard**: server-side preflight refuses three unbounded shapes — TAS `ALL` filter without `limit` ≤ 100; NASSQL pipeline starting with `FROM_*` + ALL-spec, no row-reducer, no `limit` ≤ 200; MM ALL specifier (or missing) without `clamp` ≤ 1000. The error message names the trap and points at the canonical fix. The tool description for `run_query` explicitly warns up front.

package/dist-node/host-es6fxtgx.md

@@ -0,0 +1,46 @@
+---
+id: host
+title: host — uppercase HOST vs mixed-case Host
+aliases: [hosts, machine, server]
+category: topology
+related: [agent]
+tags: [overloaded, disambiguation, core]
+---
+
+# host
+
+`HOST` and `Host` are **different vertex types** in DXO2 and frequently coexist on the same tenant:
+
+| Type | Source | Layer | Notes |
+|---|---|---|---|
+| `HOST` | APM Infrastructure Agent | INFRASTRUCTURE | The default APM-flavored host record. Has APM-style attributes (`SourceProduct`, `agent`, `acn_loganalytics_key`). |
+| `Host` | NetOps / Spectrum | INFRASTRUCTURE_UIM | NetOps-style record. Has Spectrum-style attributes (`alias`, `CSType`, `ProbeName`, `correlationNames`). |
+| `Host_Device` | NetOps / Spectrum | NETWORK_SPECTRUM | A NetOps host record that also has device-level info attached. |
+| `LPAR_HOST` | Mainframe integration | INFRASTRUCTURE | IBM LPAR-style logical host. |
+| `k8s_NODE` | Kubernetes agent | INFRASTRUCTURE | Worker node in a Kubernetes cluster — k8s-flavored counterpart to `HOST`. |
+
+## Why this matters
+
+A query filtering on `type=HOST` excludes NetOps `Host` records entirely. On a tenant that monitors with both APM *and* NetOps, that's roughly half the actual machine inventory. To fetch all hosts regardless of source, filter:
+
+```
+ATTRIBUTE type IN ["HOST", "Host", "Host_Device", "LPAR_HOST"]
+```
+
+(Optionally include `k8s_NODE` if k8s nodes-as-hosts make sense for the question.)
+
+## How users phrase it
+
+- "the host" / "this server" / "the box" — usually want the union; default to all flavors and let the answer explain.
+- "the APM host" → just `HOST`.
+- "the NetOps host" → `Host` / `Host_Device`.
+- "the node" → ambiguous; in k8s shops `k8s_NODE`, otherwise `HOST`.
+
+## Cross-flavor matching
+
+`HOST` and `Host` for the same physical machine are **separate vertices** with **no edge between them**. To match across, use attribute similarity on `acnHostName`, `acnOtherHostNames`, `dx_hostname_list`, or IP address. See `cookbooks/entity-relationships`.
+
+## See also
+
+- `entities/host` — APM HOST detail.
+- `cookbooks/entity-relationships` — attribute-similarity matching across flavors.

package/dist-node/host-j3qqrm5f.md

@@ -0,0 +1,55 @@
+---
+id: host
+title: HOST — physical or virtual machine in the topology
+layer: INFRASTRUCTURE
+synonyms: [machine, node, server]
+related_entities: [agent, k8s_node]
+related_cookbooks: [tas-quickstart]
+tags: [infrastructure, core]
+---
+
+# HOST
+
+## What it is
+
+A HOST vertex represents one machine — physical, VM, container host, or a cloud-managed compute resource — that is reporting telemetry or has been discovered by an agent. Hostnames, IPs, MAC addresses, OS-level inventory all hang off the HOST as attributes.
+
+## Where it lives
+
+`type=HOST` vertices live in the **INFRASTRUCTURE** layer.
+
+**NOT in APM_INFRASTRUCTURE.** That layer holds AGENT, AGENT_CONNECTION, DXI_SERVICE, and other APM-specific telemetry concepts. This is a common confusion: "APM hosts" naturally suggests `APM_INFRASTRUCTURE` but you'll get back agents, not hosts.
+
+To find HOSTs that participate in APM, filter `INFRASTRUCTURE.HOST` by `SourceProduct=APM`.
+
+## Common uses
+
+- **Inventory queries** — list all hosts on the tenant, optionally filtered by `SourceProduct`, `agent`, `dx_hostname`, etc.
+- **Traversal seed** — TRAVERSE from a HOST to find its agents (forward edges) or its k8s pods (forward edges to k8s entities).
+- **Cardinality estimation** — counting HOSTs gives a rough sense of monitored fleet size.
+
+## Useful attributes
+
+- `hostname` / `dx_hostname` — primary name (canonical: `dx_hostname`).
+- `dx_ip_address` / `dx_ip_address_list` — IP(s) the host has been seen with.
+- `SourceProduct` — array of products that report telemetry from this host (`APM`, `DXIM`, etc.). Useful for filtering.
+- `agent` — array of agent identity strings on this host.
+- `category` — high-level grouping ("System", etc.).
+- `compacted` / `hidden` — internal flags; rarely useful for filtering.
+
+## Common synonyms / mistakes
+
+- "machine", "node", "server" — all map to HOST in user vocabulary.
+- **"k8s host" / "k8s node"** — different! `k8s_NODE` is its own type. A `k8s_NODE` is the in-cluster representation; the HOST is the underlying VM. Some tenants surface both for the same physical machine.
+- "physical host" — there's no separate type; HOST covers physical and virtual.
+
+## Related entities
+
+- **AGENT** (in APM_INFRASTRUCTURE) — typically reachable via TRAVERSE from a HOST.
+- **k8s_NODE** (in INFRASTRUCTURE) — Kubernetes-cluster-side view of a node. May co-exist with HOST.
+
+## See also
+
+- `cookbooks/tas-quickstart` — the layer + ATTRIBUTE pattern that returns HOSTs.
+- `queries/01-discover-vertices` — sample TAS query that returns 20 vertices including HOSTs.
+- `queries/02-discover-services` — pulls HOSTs alongside other top-level types.

package/dist-node/index-104hyb1m.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en" data-beasties-container>
+  <head>
+    <meta charset="utf-8">
+    <title>dx-do · query builder</title>
+    <base href="/">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link rel="icon" type="image/x-icon" href="favicon.ico">
+  <style>@-webkit-keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0)}to{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}:root{color-scheme:dark;--dx-accent:#86efac;--dx-accent-strong:#34d399;--dx-accent-soft:rgba(134, 239, 172, .1);--dx-accent-amber:#fbbf24;--dx-glow:0 0 12px rgba(134, 239, 172, .4);--dx-glow-amber:0 0 12px rgba(251, 191, 36, .35);--dx-bg-canvas:#0a0a0a;--dx-bg-canvas-vignette:radial-gradient( ellipse at center, #161616 0%, #0a0a0a 70% );--dx-sidebar-bg:rgba(18, 18, 20, .94);--dx-sidebar-border:rgba(255, 255, 255, .06);--dx-text:#e5e5e5;--dx-text-muted:#a3a3a3;--dx-text-subtle:#737373}html,body{margin:0;padding:0;height:100vh;font-family:-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,sans-serif;background:var(--dx-bg-canvas);color:var(--dx-text)}.dx-app-body{background:var(--dx-bg-canvas);color:var(--dx-text)}</style><link rel="stylesheet" href="styles-23VUPSCU.css" media="print" onload="this.media='all'"><noscript><link rel="stylesheet" href="styles-23VUPSCU.css"></noscript></head>
+  <body class="dx-app-body">
+    <dx-app></dx-app>
+  <link rel="modulepreload" href="chunk-JRM4BLOM.js"><link rel="modulepreload" href="chunk-YVD3UK5I.js"><link rel="modulepreload" href="chunk-Q2JA73UH.js"><link rel="modulepreload" href="chunk-RNMHSXZF.js"><link rel="modulepreload" href="chunk-5VSFINOX.js"><script src="polyfills-A7ZF72EO.js" type="module"></script><script src="main-SGLYO5YX.js" type="module"></script></body>
+</html>