# 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

```zparql
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

| Pattern | Meaning | Example |
| :--- | :--- | :--- |
| `(n:kind)` | Node of specific kind | `(b:backlog_item)` |
| `(n {prop: val})` | Node filtered by property | `(p {status: 'in_progress'})` |
| `-[r:rel]->` | Directed outgoing edge | `(p)-[:items]->(b)` |
| `<-[r:rel]-` | Directed incoming edge | `(c)<-[:criteria_refs]-(b)` |
| `-[r:rel]-` | Undirected edge | `(a)-[:connected_to]-(b)` |
| `-[r:rel*min..max]->` | Depth-bounded multi-hop | `(b)-[:depends_on*1..4]->(dep)` |

### 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
```zparql
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)
```zparql
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

```zql
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

```zql
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`
```bash
# 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`
```bash
# 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):

| Component / Operation | Graph Scale / Scope | Latency | Throughput | Allocations |
| :--- | :--- | :--- | :--- | :--- |
| **ZPARQL Lexing & Parsing** | Complex query with WHERE, ORDER BY, LIMIT | **7.6 µs** | 148,221 ops/sec | 9.7 KB / op |
| **ZPARQL Multi-Hop Traversal** | 100 nodes, 2 hops, filtered & projected | **103 µs** | 9,616 ops/sec | 107 KB / op |
| **ZPARQL Multi-Hop Traversal** | 1,000 nodes, 2 hops, filtered & projected | **1.29 ms** | 770 ops/sec | 1.03 MB / op |
| **ZPARQL Multi-Hop Traversal** | 10,000 nodes, 2 hops, filtered & projected | **11.3 ms** | 88 ops/sec | 9.46 MB / op |
| **ZQL Lexing & Parsing** | 5-statement atomic transaction | **10.5 µs** | 117,129 ops/sec | 15.3 KB / op |
| **ZQL Kahn Topological Sort** | 5 interdependent statements DAG resolution | **1.6 µs** | 719,541 ops/sec | 5.3 KB / op |
| **ZQL Atomic Execution** | Full validation, staging, commit, receipt | **7.2 µs** | 169,521 ops/sec | 10.0 KB / op |

### 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.