EQL — Epistemic Query Language Specification v0.1

Status: Draft Date: March 2026 Reference Implementation: @epistemicdb/eql (npm)

1. Overview

EQL (Epistemic Query Language) is a domain-specific query language for EpistemicDB. It operates on epistemic primitives — Knowledge Objects (KOs), gaps (Q-KOs), bonds, and molecules — not rows, nodes, or vectors.

2. Formal Grammar (EBNF)

Program           = Statement { Statement } ;
Statement         = FetchStatement
                  | OpenGapsStatement
                  | ProjectDecayStatement
                  | ComposeStatement
                  | WatchStatement ;

FetchStatement    = "FETCH" FetchTarget
                    [ WhereClause ]
                    [ AsClause ]
                    [ OrderClause ]
                    [ LimitClause ] ;

OpenGapsStatement = "OPEN" "GAPS"
                    [ WhereClause ]
                    [ OrderClause ]
                    [ LimitClause ] ;

ProjectDecayStatement = "PROJECT" "DECAY"
                    [ WhereClause ]
                    [ ReturnClause ] ;

ComposeStatement  = "COMPOSE" "FROM" "MOLECULE"
                    WhereClause
                    "USING" "OPERATOR" ComposeOperator ;

WatchStatement    = "WATCH" FetchTarget
                    [ WhereClause ]
                    [ AsClause ] ;

FetchTarget       = "KO" | "D-KO" | "MOLECULE" ;
ComposeOperator   = "DERIVE" | "MERGE" | "CONTRADICT" ;

WhereClause       = "WHERE" Condition { "AND" Condition } ;

Condition         = ComparisonCondition
                  | InCondition
                  | FunctionCondition
                  | FunctionLeftCondition
                  | BlockingCondition
                  | SourceConfidenceCondition ;

ComparisonCondition    = Field Operator Value ;
InCondition            = Field "IN" "(" Value { "," Value } ")" ;
FunctionCondition      = Field Operator FunctionCall ;
FunctionLeftCondition  = FunctionCall Operator Value ;
BlockingCondition      = "blocking" ( "ANY" | "ALL" ) EpistemicClass ;
SourceConfidenceCondition = "confidence" ( ">" | ">=" ) "min_source_confidence" "+" Number ;

FunctionCall      = Identifier "(" [ Value { "," Value } ] ")" ;

AsClause          = "AS" "projection" ProjectionType ;
OrderClause       = "ORDER" "BY" Field [ Direction ] ;
LimitClause       = "LIMIT" Number ;
ReturnClause      = "RETURN" Identifier { "," Identifier } ;

Field             = Identifier { "." Identifier } ;
Operator          = ">" | "<" | ">=" | "<=" | "=" | "!=" ;
Direction         = "ASC" | "DESC" ;

Value             = Number | String | Boolean | "null"
                  | EpistemicClass | ProjectionType | Duration ;

Number            = Digit { Digit } [ "." Digit { Digit } ] ;
String            = '"' { Character } '"' ;
Boolean           = "true" | "false" ;
Duration          = ( "+" | "-" ) Digit { Digit } DurationUnit ;
DurationUnit      = "d" | "w" | "m" | "y" ;

ProjectionType    = "STRUCTURAL" | "DYNAMIC" | "CONSTRAINT" | "COMPOSITIONAL" ;

EpistemicClass    = "DECISION" | "EVIDENCE" | "OBSERVATION" | "HYPOTHESIS"
                  | "PLAN" | "CONSTRAINT" | "NARRATIVE"
                  | "Q_FACTUAL" | "Q_DECISION" | "Q_STRATEGIC" ;

Identifier        = Letter { Letter | Digit | "_" } ;
Letter            = "a" .. "z" | "A" .. "Z" | "_" ;
Digit             = "0" .. "9" ;
Character         = ? any character except unescaped '"' ? ;
Comment           = "--" { ? any character except newline ? } ;

3. Statement Types

FETCH — Retrieve knowledge objects

FETCH <target>
  [WHERE <conditions>]
  [AS projection <projection_type>]
  [ORDER BY <field> [ASC|DESC]]
  [LIMIT <n>]

Where <target> is one of: KO, D-KO, MOLECULE

OPEN GAPS — Retrieve blocking unknowns

OPEN GAPS
  [WHERE <conditions>]
  [ORDER BY <field> [ASC|DESC]]
  [LIMIT <n>]

PROJECT DECAY — Forward-looking staleness

PROJECT DECAY
  [WHERE <conditions>]
  [RETURN <field_list>]

COMPOSE — Trigger D-KO synthesis

COMPOSE
  FROM MOLECULE
  WHERE <conditions>
  USING OPERATOR <DERIVE|MERGE|CONTRADICT>

WATCH — Live subscriptions

WATCH <target>
  [WHERE <conditions>]
  [AS projection <projection_type>]

4. WHERE Clause

Conditions are separated by AND:

WHERE entity = "ai-triage"
  AND decay_score > 0.40
  AND confidence > 0.60

Condition types

Pattern	Example
Field comparison	decay_score > 0.35
String equality	entity = "pricing"
IN list	epistemic_class IN (DECISION, PLAN)
Function on right	decay_score < decay_score_at(+30d)
Function on left	decay_score_at(+30d) < 0.35
Blocking filter	blocking ANY DECISION
Source confidence	confidence > min_source_confidence + 0.10

Operators

=, !=, >, <, >=, <=

Restrictions:

• decay_score only accepts >, <, >=, <= (no equality on continuous floats)
• blocking conditions only valid in OPEN GAPS
• urgency field only valid in OPEN GAPS
• decay_score_at() only valid in PROJECT DECAY or FETCH
• confidence > min_source_confidence + N only valid in FETCH
• COMPOSE WHERE must include both coherence and reaction_potential

5. Field Types

Field	Type	Range	Context
entity	string	—	all
epistemic_class	EpistemicClass	enum	all
decay_score	float	[0, 1]	all
confidence	float	[0, 1]	all
k_score / K	float	[0, ∞)	all
epistemic_mass	float	[0, ∞)	all
informational_charge	float	[-1, 1]	all
generativity	float	[0, 1]	all
plasticity	float	[0, 1]	all
constraint_force	float	[0, 1]	all
is_derived	boolean	—	all
is_active	boolean	—	all
urgency	float	[0, 1]	OPEN GAPS only
coherence	float	[0, 1]	COMPOSE only
reaction_potential	float	[0, 1]	COMPOSE only

6. Projection Types

Type	Returns
STRUCTURAL	class, position, confidence, mass, stability
DYNAMIC	velocity, drift direction, trend label, acceleration
CONSTRAINT	constraint force, downstream blocked KOs, coupling
COMPOSITIONAL	generativity, plasticity, charge, affinity classes

7. Epistemic Classes

DECISION, EVIDENCE, OBSERVATION, HYPOTHESIS, PLAN, CONSTRAINT, NARRATIVE, Q_FACTUAL, Q_DECISION, Q_STRATEGIC

8. Duration Literals

Format: [+-]<number><unit> where unit is d (days), w (weeks), m (months), y (years).

Pre-parsed to days: +30d → 30, +1w → 7, +1m → 30, +1y → 365.

Duration of 0 days is invalid.

9. Built-in Functions

Function	Arguments	Returns	Valid in
decay_score_at	duration	float [0, 1]	PROJECT DECAY, FETCH
confidence_at	duration	float [0, 1]	FETCH
urgency_at	duration	float [0, 1]	OPEN GAPS

10. Comments

Line comments: -- this is a comment

11. Error Codes

Code	Description
INVALID_FIELD_FOR_CONTEXT	Field used outside its valid context
INVALID_OPERATOR_FOR_TYPE	Operator incompatible with field type
INVALID_OPERATOR_FOR_DECAY_SCORE	Equality operator on decay_score
INVALID_FUNCTION_FOR_CONTEXT	Function used outside valid context
INVALID_FUNCTION_ARGS	Wrong arguments for function
INVALID_CONDITION_FOR_CONTEXT	Condition type invalid in context
ZERO_DURATION	Duration literal with 0 days
COMPOSE_MISSING_WHERE	COMPOSE without WHERE clause
COMPOSE_MISSING_COHERENCE	COMPOSE WHERE missing coherence
COMPOSE_MISSING_REACTION_POTENTIAL	COMPOSE WHERE missing reaction_potential
VALUE_OUT_OF_RANGE	Warning: value outside expected range
UNUSUAL_OPERATOR_FOR_STRING	Warning: comparison op on string field

---

EQL Specification v0.1 — March 2026Reference: @epistemicdb/eql npm package