catalyst-events query — natural-language event triage

TL;DR

catalyst-events query "errors in the last hour"
catalyst-events query "show all gh events for ADV-292 and ADV-293 that are PR or CI" --explain
catalyst-events query "failed CI on main branch" --since 1d --limit 50

In the TUI (catalyst-hud):

When to use this

• You want to triage events across orchestrators / tickets / PRs and don't want to memorize the jq attribute paths.
• You're explaining a query in a doc or skill and want a copy-pasteable command.
• You're building a dashboard or report and want a one-liner that returns the right slice of the event log.

When NOT to use this

• You're inside an automated waiter — use catalyst-events wait-for --filter '<jq>' directly. The query subcommand pays a Groq round-trip; waiters need to be deterministic.
• You're filtering by a single canonical attribute path you already know — catalyst-events tail --filter '...' is faster.

DSL grammar

The compiler accepts a strict JSON DSL. You don't normally write this by hand — Groq emits it — but --explain shows it to you, and --dsl lets you bypass Groq for tests / scripts.

type Dsl = {
  filter: Node;
  sort?:  { field: string; order?: "asc" | "desc" } | null;
  limit?: number | null;
} | { error: string };

type Node = And | Or | Not | Leaf | {};
type And  = { and: Node[] };
type Or   = { or:  Node[] };
type Not  = { not: Node };
type Leaf = { field: string } & (
    { eq: any } | { ne: any }
  | { gt: any } | { gte: any } | { lt: any } | { lte: any }
  | { in: any[] }
  | { startsWith: string } | { endsWith: string } | { contains: string }
  | { exists: boolean }
);

field MUST be a path from the canonical event schema — see [[event-schema]] for the authoritative list. Top-level fields (ts, severityText, severityNumber, traceId, spanId, resource."service.name", body.message) and all attributes."<key>" paths are accepted. The validator rejects anything else with a "did you mean" suggestion.

Acceptance examples (these all work)

The {NOW-1h} / {TODAY} placeholders are rewritten to ISO timestamps by the caller (CLI or TUI) before evaluation, so the model can stay deterministic.

Flags

Exit codes

The compiler error always names the bad field on stderr:

$ catalyst-events query --dsl '{"filter":{"field":"bogus.field","eq":1}}'
{"error":"unknown field: bogus.field","code":"unknown_field","field":"bogus.field"}

Configuration

Internals

• The CLI is plugins/dev/scripts/catalyst-events::cmd_query. It shells to plugins/dev/scripts/lib/dsl-cli.mjs (Node), which calls Groq, parses, validates, and emits compiled artifacts on stdout. The bash wrapper then splices the jq predicate into the existing apply_filter pipeline.
• The TUI imports the same compile() and groqTranslate() from plugins/dev/scripts/lib/dsl-compile.mjs directly — no subprocess. The DSL produces a JS predicate function evaluated in-memory against the TUI's event backbuffer.
• The system prompt + few-shot examples live in plugins/dev/scripts/lib/dsl-prompt.mjs and the canonical field whitelist in plugins/dev/scripts/lib/dsl-fields.mjs. Both are read by tests, so prompt/validator drift is caught.
• See [[event-schema]] for the canonical attribute paths the DSL targets, and [[wait-for-github]] for the deterministic-filter pattern when you need to block on a known event shape.

Out of scope

• Trace pivot from PR number ("show events with the same trace as PR #501") — needs a two-step lookup (PR → traceId → query). Returns refused for now; future ticket will add a {lookup, then} DSL.
• Streaming / --follow mode — query is one-shot; use catalyst-events tail --filter '<jq>' for live tail.
• Free-text NLP over body.payload — the DSL is structured-attribute only.

Related

• [[event-schema]] — canonical envelope and attribute reference
• [[monitor-events]] — wait-for / tail patterns for automated waiters
• [[wait-for-github]] — REST + event-tunnel two-phase wait for PR/CI lifecycle
• [[broker]] — the daemon that uses Groq for semantic event routing (not event queries)