Skip to content

SPEC-EVO-004 — QLens Query Language

Purpose

QLens Query Language, abbreviated QLQ, provides stable structural queries over objects, relationships, lifecycle state, and time.

Initial query capabilities

QLQ MUST support filtering by OID, type, status, space, tag, version, path, and timestamp. It MUST support relationship predicates and reverse traversal.

Representative queries include:

FROM evidence WHERE space = "SPACE-QURAN"
FROM meaning WHERE NOT incoming("supports")
FROM reasoning WHERE depends_on("EVIDENCE-001")
FROM question WHERE status IN ("open", "collecting")
NEIGHBORS "MEANING-001" DEPTH 2
CONTRADICTIONS OF "HYPOTHESIS-001"
AT "2026-01-01T00:00:00Z" FROM meaning

Requirements

  1. Query results MUST be read-only unless a separate explicit mutation command is invoked.
  2. Identical repository state and query text MUST produce deterministic ordering or declare an ordering requirement.
  3. Queries MUST fail clearly on unknown fields and malformed predicates.
  4. Time-qualified queries MUST define whether they use object metadata history, Git history, or both.
  5. The CLI MUST support machine-readable JSON output.
  6. NUR MAY expose visual query builders, but generated queries MUST remain inspectable.
  7. Query execution MUST NOT modify canonical files.

Security and limits

Implementations MUST enforce traversal, result-size, and execution limits when operating as a service. Local CLI operation SHOULD expose configurable limits.

Acceptance criteria

  • Users can locate orphan objects and unsupported meanings.
  • Reverse dependency queries return all direct dependents.
  • JSON output is stable enough for automation within a declared format version.
  • A malformed query never produces partial writes.