LLM grammar pack (SignalQL v0.4)

Compact reference for prompts and MCP resources covering the current language surface (v0.1 → v0.4). Pair with the v0.4 specification, v0.3 specification, scope, and the versions index.

Core contract (all versions): SignalQL retrieves and shapes structured evidence and lineage. It does not interpret, score, decide, or mutate — that is the AI/reasoning layer's job.

Grammar summary by version

v0.1/v0.2 — analytics + evidence retrieval

• Counts/funnels (v0.1): COUNT events|users FROM events WHERE … DURING LAST N DAYS [GROUP BY DAY], FUNNEL "a" THEN "b" …
• Retrieve/traverse/trend/sequence: FROM entity(type)|events …, TRAVERSE rel DEPTH <= N, TREND UP|DOWN|FLAT OVER Nd|Nh|Nw, FIND sequence WHERE a -> b -> c WITHIN Nd
• Derived fields: signal(name), probability(name), semantic_match("…")

v0.3 — aggregation, metrics, headless surfaces

• FROM events … [GROUP BY a, b] [BUCKET BY d|w|h|m] [HAVING …] [ORDER BY … ] [LIMIT n] RETURN <aggregates>
• Aggregates: count(), count_distinct(f), sum/avg/min/max(f), variance/stddev(f), percentile(f, p), stats(f) (sufficient statistics for A/B)
• Filters: =, !=, <, >, <=, >=, IN, NOT IN, BETWEEN, CONTAINS, IS [NOT] NULL, AND, OR, NOT
• Reproducibility: AS OF "ts"; governed metrics: FROM metric(name); introspection: DESCRIBE entities|events|signals|metrics|relationships

v0.4 — Operational Graph (current)

• Pattern: MATCH entity(a) -[rel]-> entity(b) [WHERE …] [WITHOUT rel]* [AS OF "ts"] RETURN entity_id [LIMIT n]
• Reachability: FIND entity(a) CONNECTED TO entity(b) [WHERE …] [VIA rel] [DEPTH <= n] RETURN entity_id
• Path: PATH FROM entity(a) TO entity(b) [VIA rel]
• Lineage: TRACE entity(x) WHERE … [VIA derived_from] [DEPTH <= n] [AS OF "ts"] → ordered evidence chain
• Context bundle: CONTEXT FOR entity(x) [DEPTH <= n] [INCLUDE entities, relationships, evidence, …] [AS OF "ts"]

Canonical output format

Ask the AI to emit:

1. SignalQL query in canonical clause order.
2. Brief rationale for retrieval intent only.
3. Expected structured output fields (or lineage/bundle shape for v0.4).
4. Explicit statement that interpretation is external.

When to ask for schema first

Use DESCRIBE (or ask the user) for entity types, relationship names, signal/metric catalog keys, and event names before emitting SignalQL if:

• the source domain is unfamiliar,
• graph traversal / lineage / a governed metric(...) is requested,
• derived/probabilistic signals are referenced.

Canonical valid examples

FROM events WHERE event_name = "purchase" DURING LAST 14 DAYS
GROUP BY properties.experiment_variant
RETURN properties.experiment_variant, count_distinct(user_id), stats(properties.amount)

MATCH entity(assumption) WITHOUT validated_by RETURN entity_id

TRACE entity(ticket) WHERE id = "123" VIA derived_from DEPTH <= 6

CONTEXT FOR entity(roadmap) WHERE quarter = "Q3" DEPTH <= 2 INCLUDE entities, relationships, evidence

Canonical invalid examples

Bad snippet	Why
ASSIGN owner = "sam"	Action/mutation is out of scope
FROM entity(work_item) WHERE sprint = "Q2"	Domain-specific nouns are not core
WHERE blocked = true / FIND … AT RISK	Built-in business interpretation is not core (use signal(...) or WITHOUT rel)
Raw SQL SELECT	Not a SignalQL surface

Intent → shape

User intent	Shape
Metric over time	FROM events … BUCKET BY d RETURN count_distinct(user_id)
A/B evidence	… GROUP BY signal(experiment_variant) RETURN stats(metric)
Dependency blast radius	MATCH entity(x) -[rel]-> entity(y) RETURN entity_id / FIND … CONNECTED TO …
Missing evidence	MATCH entity(assumption) WITHOUT validated_by RETURN entity_id
"Why does this exist?"	TRACE entity(x) VIA derived_from
LLM-ready context	CONTEXT FOR entity(x) DEPTH <= n INCLUDE …
As believed at a past date	append AS OF "ts"

Relationship vocabularies (supports, derived_from, …) come from external domain packs (e.g. aspectgraph-work-pack), not core.

Copy this file into Cursor rules, Claude project knowledge, or MCP resources as needed.