Agent & Developer Guide: Declarative Graph Queries (ZPARQL) and Atomic Mutations (ZQL)

1. Executive Summary

Autonomous agents and human operators interact extensively with the ZQK Knowledge Kernel, a rich multi-layered directed graph where nodes represent typed entities (goal, milestone, priority_plan, backlog_item, criteria, test_case, policy, persona, prompt) and edges represent semantic relationships (parent_ref, depends_on, criteria_refs, test_case_refs, etc.).

Historically, querying topological relationships required multi-step sequential CLI scripts or procedural BFS/DFS traversals in Go. Similarly, creating interdependent object trees required multiple CLI calls (zqk object create ...) with manual ID extraction, creating fragility and risking orphaned objects when intermediate steps failed.

With the introduction of ZPARQL (Declarative Graph Query Language) and ZQL (Declarative Mutation Language), agents achieve dramatic friction reduction:

• Declarative Graph Queries: Complex multi-hop traversals and Definition of Done (DoD) verification run in a single Cypher/SPARQL-like pattern query.
• Atomic Multi-Object Mutations: Multi-object creation and relationship wiring execute in a single ACID transaction with Kahn topological variable resolution and guaranteed rollback.
• Native Dual Interfaces: Accessible both via CLI (zqk query, zqk mutate) and MCP tools (query_zparql, mutate_zql).

---

2. ZPARQL: Declarative Graph Query Language

Conforming to SPEC-ZPARQL-GRAPH-TRAVERSAL-GRAMMAR.

2.1 Core Syntax

MATCH path_pattern [, path_pattern ...]
[WHERE boolean_expression]
RETURN [DISTINCT] projection [, projection ...]
[ORDER BY property [ASC | DESC]]
[LIMIT n [OFFSET m]];

2.2 Path Patterns & Edge Traversals

2.3 WHERE Predicates

Supports binary comparisons and boolean logic:

• Equality & Inequality: =, !=
• Numeric comparisons: <, <=, >, >=
• String matching: CONTAINS
• Set inclusion: IN ["val1", "val2"]
• Logical composition: AND, OR, NOT, (...)

2.4 Projections & Aggregates

• Scalar properties: RETURN b.id AS bli_id, b.title AS title
• Aggregations: COUNT(*), COUNT(b.id), COLLECT(b.id)
• Deduplication: RETURN DISTINCT b.priority_tier

2.5 Practical Examples

Multi-Hop DoD Verification Query

MATCH (p:priority_plan {status: "in_progress"})-[:items]->(b:backlog_item),
      (b)-[:criteria_refs]->(c:criteria),
      (c)-[:test_case_refs]->(t:test_case)
WHERE b.status != "complete"
RETURN p.title AS plan, b.id AS bli_id, c.title AS criterion, t.id AS test_case
ORDER BY b.id ASC;

Cycle-Safe Dependency Traversal (1 to 4 Hops)

MATCH (b:backlog_item {id: "BLI-1001"})-[:depends_on*1..4]->(dep:backlog_item)
RETURN dep.id AS dependency, dep.status AS status, dep.priority_tier AS tier;

---

3. ZQL: Declarative Atomic Mutations

Conforming to SPEC-ZQL-DECLARATIVE-MUTATION-GRAMMAR.

3.1 Core Syntax

BEGIN TRANSACTION [ISOLATION LEVEL STAGED_SNAPSHOT | SERIALIZABLE | READ_COMMITTED];

LET $variable = expression;
LET $variable = UPSERT kind [ID id] WITH { ... } [RETURNING ...];

UPSERT kind [ID id] WITH {
    field1: value1,
    field2: $variable.field
};

DELETE kind id [CASCADE | RESTRICT];

COMMIT TRANSACTION;

3.2 Topological Variable Resolution (Kahn's Algorithm)

Statements in a ZQL transaction block can reference variables defined anywhere in the block. The compiler constructs a dependency DAG (\(s_j \to s_i\)) and schedules execution order via Kahn's algorithm:

• Forward references and backward references resolve automatically.
• Unbound variables trigger ERR_ZQL_UNBOUND_VARIABLE before write initiation.
• Circular references trigger ERR_ZQL_CIRCULAR_DEPENDENCY before write initiation.

3.3 Atomic Workstream Initiation Example

BEGIN TRANSACTION ISOLATION LEVEL STAGED_SNAPSHOT;

LET $ws_title = "Swarm Telemetry Overhaul";

LET $plan = UPSERT priority_plan {
    title: $ws_title,
    priority_tier: "P1",
    status: "in_progress",
    description: "Multi-seat event streaming pipeline"
} RETURNING id;

UPSERT backlog_item {
    title: "Implement Stream Consumer Daemon",
    priority_plan_ref: $plan.id,
    priority_tier: "P1",
    status: "planned",
    estimated_effort: "4h"
};

UPSERT backlog_item {
    title: "Stream Buffer Shockwave Verification",
    priority_plan_ref: $plan.id,
    priority_tier: "P1",
    status: "planned",
    estimated_effort: "2h"
};

COMMIT TRANSACTION;

---

4. Usage Interfaces

4.1 CLI Frontends

zqk query

# Direct inline query
zqk query "MATCH (b:backlog_item) WHERE b.status = 'planned' RETURN b.id, b.title;"

# Output as structured JSON
zqk query "MATCH (p:priority_plan) RETURN p.id, p.title;" --format json

# Execute from query file
zqk query -f queries/open_dependencies.zparql

zqk mutate

# Validate mutations in preflight dry-run (no storage writes)
zqk mutate -f scripts/init_stream.zql --dry-run

# Commit atomic transaction
zqk mutate -f scripts/init_stream.zql

# Inline mutation
zqk mutate "BEGIN; UPSERT priority_plan { title: 'P1 Plan', priority_tier: 'P1', status: 'in_progress' }; COMMIT;"

4.2 MCP Server Tools (For AI Agents)

Agents connected over Model Context Protocol (MCP) can invoke declarative tools directly without invoking subshell commands:

Tool: query_zparql

• Parameters:
• query (string, required): The ZPARQL query string.
• format (string, optional): "json" (default) or "table".
• Response: Tabular JSON object containing headers, rows, and total.

Tool: mutate_zql

• Parameters:
• script (string, required): The ZQL script.
• dry_run (boolean, optional): Default false. If true, runs preflight validation without writing.
• Response: ZQLExecutionReceipt containing transaction_id, isolation_level, committed, receipts, and bindings.

---

5. Performance Benchmarks

Performance was verified using Go benchmarks on Apple Silicon (M1 Max):

Key Takeaways

1. Sub-millisecond Traversals: Standard query workloads on graphs up to 1,000 nodes complete in ~1 ms with bounded memory overhead.
2. High-Frequency Mutations: Atomic mutations complete in ~7 µs, capable of supporting swarms issuing hundreds of transactions per second.
3. No Database Dependencies: The engine operates purely in-memory and against CAS storage, eliminating the need for Neo4j/MemGraph daemon processes.