SignalQL v0.5 specification — Information Objects

Status: Draft with reference implementation. v0.5 extends the v0.4 Operational Graph so that files, documents, messages, code, media, and generated artifacts are queryable as stable, versioned, provenance-aware objects, and makes CONTEXT FOR a budgeted, inspectable retrieval primitive for AI agents. It is additive: every v0.4 query keeps its meaning, its AST, and its compiled SQL. The reference compiler implements every surface below as parameterized SQL plus an in-memory reference runtime.

v0.5 is specified across several documents:

Document	Covers
this page	scope, principles, lexical changes, full grammar, tiers, capability discovery
Object model	OBJECT, REVISION, REPRESENTATION, object vs entity, logical sources
Provenance	DERIVATION, dependency state, FIND OBJECT, FIND DEPENDENTS, TRACE OBJECT / TRACE CLAIM
Context	CONTEXT FOR "task", budgets, PREFER / EXCLUDE, trust and roles, context bundles, EXPLAIN CONTEXT, FIND OBJECT ABOUT
Examples	worked examples against the reference fixture
Command notes	non-normative notes on the future write protocol

The milestone

An AI agent can ask SignalQL for the smallest relevant, current, trusted, provenance-preserving set of information required for a task, without needing to know whether that information originated as a file, graph node, message, database row, or generated artifact.

CONTEXT FOR "design SignalQL object storage"
USING PROJECT "SignalQL"
BUDGET 32000 TOKENS
PREFER CURRENT, VERIFIED
WITH EVIDENCE

returns an inspectable, reproducible Context Bundle assembled from multiple representations and revisions.

The canonical chain v0.5 defines is

OBJECT → REPRESENTATION → REVISION → DERIVATION → CONTEXT

so that a storage architecture can be chosen later without a database, graph store, object store, or filesystem convention dictating the model.

Scope

SignalQL stays a read language. v0.5 adds the semantics needed to address information objects and nothing that changes them:

SignalQL          → read / query / resolve / context / trace
SignalQL-Command  → create / derive / revise / relate / tombstone / commit   (not this language)

A statement that begins with a write verb (CREATE, DERIVE, REVISE, RELATE, TOMBSTONE, DROP, MERGE, SUBSCRIBE, BEGIN, COMMIT) MUST be rejected with a parse error.

Preserved core principles

• Retrieval and shaping only; no mutation.
• No interpretation labels in core. v0.5 adds computed facts about revisions (dependency state), never judgments.
• The language exposes metadata (origin, trust, validation, role); domains define what earns each value.
• Backward compatible: v0.1–v0.4 queries parse to the same AST and compile to the same SQL. The reference implementation enforces this against a golden corpus captured from the v0.4 release (fixtures/v04-ast-golden.json).

Core vocabulary added

v0.4 kept relationship vocabulary in domain packs. v0.5 moves a small, closed set into core because the semantics above depend on it: the five derivation relations, the dependency states, and the origin, trust, validation, and role value sets. project is an opaque partition label. Object types, representation names, and all other relationships remain data, defined by packs.

Lexical changes

These apply to every version's grammar and are strictly more permissive than v0.4 — no previously valid query changes meaning.

Object and context addresses

object_uri  ::= "object://" node_id ( "@" integer )?
context_uri ::= "context://" node_id
node_id     ::= [A-Za-z0-9] [A-Za-z0-9._~-]*

An address is a single token. @n names revision n of the object and is only valid on object://.

Quotes inside string literals

A doubled quote inside a string literal denotes one quote character: "the ""final"" draft" is the string the "final" draft. Canonical query text MUST escape quotes this way, so canonical text re-parses to the same AST.

Contextual keywords

v0.5 adds no reserved words. Its vocabulary (OBJECT, REPRESENTATION, REVISIONS, BUDGET, PREFER, …) is recognised only where the grammar expects it, so those words remain valid entity types, relationship names, and fields.

The same rule now applies to earlier keywords: a keyword in a name position (entity type, relationship, field, signal or metric name, funnel step) is a name. entity(metric), -[contains]->, and WHERE context = "x" are valid. Only the structural words AND, OR, NOT, IN, IS, NULL, TRUE, FALSE, BETWEEN can never be names. This supersedes the reserved-word list in v0.3.

name ::= identifier | non_structural_keyword

The retrieval-only guard reads structure, not data

The guard that rejects mutation words inspects query structure only. Text inside string literals and addresses is data: CONTEXT FOR "update the logout flow" is a valid query.

Grammar (EBNF, additive over v0.4)

v05_query ::= get_object | show_revisions | show_representations | get_representation
            | find_object | find_dependents | trace_object
            | context_task | explain_context
            | show_object_types | show_capabilities

object_ref           ::= "OBJECT" ( object_uri | name )
rep_name             ::= string_literal | name

get_object           ::= "GET" object_ref as_of_clause?
show_revisions       ::= "SHOW" "REVISIONS" "OF" object_ref as_of_clause? limit_clause?
show_representations ::= "SHOW" "REPRESENTATIONS" "OF" object_ref as_of_clause?
get_representation   ::= "GET" "REPRESENTATION" rep_name "OF" object_ref as_of_clause?

find_object          ::= "FIND" "OBJECT" ( "(" name ")" )?
                         ( "ABOUT" string_literal ( "USING" "REPRESENTATION" rep_name )? )?
                         ( "WHERE" object_predicate )? as_of_clause? limit_clause?
find_dependents      ::= "FIND" "DEPENDENTS" "OF" object_ref
                         via_derivation? depth_clause? ( "WHERE" object_predicate )?
                         as_of_clause? limit_clause?
trace_object         ::= "TRACE" ( object_ref | "CLAIM" ( object_uri | name ) )
                         via_derivation? depth_clause? as_of_clause?
via_derivation       ::= "VIA" derivation_rel ( "," derivation_rel )*
derivation_rel       ::= "derived_from" | "generated_from" | "extracted_from"
                       | "summarized_from" | "transformed_from"
depth_clause         ::= "DEPTH" "<=" integer

context_task         ::= "CONTEXT" "FOR" string_literal context_clause*
context_clause       ::= "USING" "PROJECT" string_literal
                       | "BUDGET" integer "TOKENS"
                       | "PREFER" prefer_item ( "," prefer_item )*
                       | "EXCLUDE" exclude_item ( "," exclude_item )*
                       | "MAX" ( "OBJECTS" integer | "DEPTH" integer | "AGE" integer time_unit )
                       | "WITH" "EVIDENCE"
                       | as_of_clause
prefer_item          ::= "CURRENT" | trust_level | "REPRESENTATION" rep_name
exclude_item         ::= "UNTRUSTED" | "STALE" | "ROLE" role ( "FROM" role )?
explain_context      ::= "EXPLAIN" "CONTEXT" context_uri

show_object_types    ::= "SHOW" "OBJECT" "TYPES"
show_capabilities    ::= "SHOW" "CAPABILITIES"

as_of_clause, limit_clause, time_unit, and predicate_expr are as defined in v0.3; object_predicate is predicate_expr over object fields. A bare name after OBJECT is shorthand for object://name; the canonical form is the address.

Statements that share a head word with v0.4 are distinguished by what follows it: FIND OBJECT / FIND DEPENDENTS vs FIND entity(…) CONNECTED TO and FIND sequence; TRACE OBJECT / TRACE CLAIM vs TRACE entity(…); CONTEXT FOR "…" vs CONTEXT FOR entity(…).

Capability discovery

Implementations differ. SHOW CAPABILITIES lets a client find out what one supports before relying on it, so the same query text is portable across minimal and advanced implementations.

SHOW CAPABILITIES

Returns one row per capability — capability, supported, detail:

Capability	Means
object_identity	object:// addressing
representations	multiple representations per object
revisions	explicit revisions, @rev and AS OF
derivations	revision-pinned derivation links
dependency_state	the computed state field
context_budgets	CONTEXT FOR … BUDGET; detail names the scorer and estimator
context_persistence	bundles can be resolved by address (EXPLAIN CONTEXT)
trust_metadata	origin, trust, validation
role_metadata	roles on revisions and representations

SHOW CAPABILITIES describes the implementation, not the data, so it is not compiled to SQL. An implementation MUST answer it; one that lacks a capability MUST report supported = false and return an explicit capability error for queries that need it.

SHOW OBJECT TYPES returns the object types present and how many live objects have each: type, objects.

Implementation tiers

Tier	Surfaces	Reference behaviour
v0.5-core	GET OBJECT, SHOW REVISIONS, SHOW REPRESENTATIONS, GET REPRESENTATION, FIND OBJECT … WHERE, FIND DEPENDENTS, TRACE OBJECT, TRACE CLAIM, SHOW OBJECT TYPES, dependency state	direct parameterized SQL (recursive CTEs, cycle-guarded, depth-bounded); in-memory reference runtime
v0.5-extended	CONTEXT FOR "task", FIND OBJECT ABOUT	direct SQL that returns facts or scores for the named scorer (lexical-v1); a runtime step packs the bundle. Results are deterministic per scorer, not across scorers.
v0.5-extended (guarded)	signal() / probability() / semantic_match() in object predicates	explicit capability error
v0.5-capability	SHOW CAPABILITIES, EXPLAIN CONTEXT	answered by the implementation and its context store; compile-only use returns a capability error

Determinism

• Results are ordered by explicit rules; string order is by code unit.
• Dependency state is a pure function of revision facts as of the query time.
• A bundle is deterministic for a given scorer and set of estimators, and its address is derived from its content.
• Timestamp literals without a zone are interpreted in the executing engine's session time zone; write an explicit zone for portable queries.

Non-goals (v0.5)

CREATE, UPDATE, DELETE, derivation execution, transactions, agent branches, subscriptions, OBSERVE, automatic lifecycle promotion, and distributed storage semantics are out of scope. See the command notes for where they are expected to go.

Residual limitations

• Trust metadata is not bitemporal: AS OF reproduces which revision was current, not what its trust was believed to be then.
• Roles are advisory labels. The language carries them; it does not neutralise content.
• Without AS OF, v0.4 graph operators match every stored revision of an object (see graph projection).
• The compiled SQL implements the lexical-v1 scorer. A custom relevance provider needs a runtime that supplies its own candidates.
• Access control is the deployment's responsibility; EXPLAIN CONTEXT reports the addresses of rejected objects.

Normative references

• v0.4 specification — graph model, TRACE, CONTEXT FOR entity(...), AS OF
• v0.3 specification — predicates, AS OF, result envelope, tiers
• AST schema: schemas/signalql-ast-v0.5.schema.json
• Quality gate: fixtures/v05-gate-cases.json