LLM grammar pack (SignalQL v0.5)

Compact reference for prompts and MCP resources covering the current language surface (v0.1 → v0.5). Pair with the v0.5 specification, 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

• 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"]

v0.5 — Information Objects (current)

• Address: object://id or object://id@rev (a bare name after OBJECT is shorthand)
• Read: GET OBJECT <ref> [AS OF "ts"], SHOW REVISIONS OF OBJECT <ref>, SHOW REPRESENTATIONS OF OBJECT <ref>, GET REPRESENTATION "name" OF OBJECT <ref>
• Find: FIND OBJECT[(type)] [ABOUT "text" [USING REPRESENTATION name]] [WHERE …] [LIMIT n] — fields id, type, title, project, rev, origin, trust, validation, role, state, created_at, other names are metadata keys
• Staleness: state ∈ current | possibly_stale | stale | invalid (WHERE STATE = STALE); FIND DEPENDENTS OF OBJECT <ref> [VIA rel, …] [DEPTH <= n] [WHERE …]
• Lineage: TRACE OBJECT <ref> / TRACE CLAIM <ref> [VIA derived_from|generated_from|extracted_from|summarized_from|transformed_from] [DEPTH <= n]
• Task context: CONTEXT FOR "task" [USING PROJECT "p"] [BUDGET n TOKENS] [PREFER CURRENT, VERIFIED, REPRESENTATION name] [EXCLUDE UNTRUSTED, STALE, ROLE r [FROM s]] [MAX OBJECTS n] [MAX DEPTH n] [MAX AGE n DAYS] [WITH EVIDENCE] [AS OF "ts"] → addressable bundle context://id
• Inspect: EXPLAIN CONTEXT context://id, SHOW OBJECT TYPES, SHOW CAPABILITIES
• Keywords are contextual: entity(metric) and -[contains]-> are valid; v0.5 reserves no new words

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 and v0.5).
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

CONTEXT FOR "implement logout" USING PROJECT "Strada" BUDGET 24000 TOKENS PREFER CURRENT, VERIFIED WITH EVIDENCE

FIND DEPENDENTS OF OBJECT object://source_data WHERE state != current

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
CREATE OBJECT … / DERIVE … / UPDATE …	Writes belong to SignalQL-Command, not this language
FIND OBJECT WHERE state = fresh	state has a closed vocabulary
EXPLAIN FROM events …	Only EXPLAIN CONTEXT context://id is defined

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"
Context for an agent task, within a token budget	CONTEXT FOR "task" BUDGET n TOKENS PREFER CURRENT, VERIFIED WITH EVIDENCE
Keep untrusted instructions out	… EXCLUDE UNTRUSTED, ROLE INSTRUCTION FROM UNTRUSTED_EXTERNAL
"What is out of date?"	FIND OBJECT WHERE state != current
"What breaks if this source changes?"	FIND DEPENDENTS OF OBJECT <ref>
"Where did this generated text / claim come from?"	TRACE OBJECT <ref> / TRACE CLAIM <ref>
"Why was this in the model's context?"	EXPLAIN CONTEXT context://id
What does this implementation support?	SHOW CAPABILITIES

Relationship vocabularies (supports, derived_from, …) come from external domain packs (e.g. aspectgraph-work-pack), not core. Object types and representation names are likewise pack conventions (see information-objects-pack); only the five derivation relations are core.

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