Reference Manuals
Docs » Reference Manuals » ZQL Declarative Mutations Developer Manual
Raw .md

ZQL Declarative Mutations Developer Manual

Overview

ZQL (ZQK Query Language - Mutation Engine) is the declarative mutation language for executing deterministic, ACID-compliant modifications across the Knowledge Kernel graph. ZQL statements guarantee referential integrity, trigger automatic shockwave propagation, and log all state changes to the Write-Ahead Log (WAL).

1. Declarative Mutation Anatomy

ZQL mutations can be expressed via high-level declarative syntax or structured documents. A mutation directive specifies target match criteria, transformations to apply, and pre- or post-flight validation rules:

MUTATE backlog_item
WHERE id = "BLI-SAMPLE-001"
SET {
    title: "Updated Task Title",
    priority_tier: "P1",
    estimated_effort: "4h"
}
ASSERT criteria_refs IS NOT EMPTY

2. The apply Operation

To execute mutations safely, ZQL provides an apply execution pathway. The engine evaluates preconditions in memory, validates the proposed object state against the schema and lifecycle definitions, and then writes the result atomically through the CAS membrane.

CLI Execution

# Apply a declarative mutation payload from a file
zqk mutate --file mutations/update_task.zql.yaml

# Apply mutations with strict pre-condition enforcement
zqk mutate --dry-run --file mutations/batch_realign.zql.yaml

Mutation Payload Example (update_task.zql.yaml)

version: "1.0.0"
operation: "apply"
target:
  kind: "backlog_item"
  id: "BLI-DOC-LANGUAGES"
mutations:
  - set:
      status: "testing"
      artifacts:
        - "docs/manual/ZPARQL_QUERY_LANGUAGE.md"
        - "docs/manual/ZQL_MUTATIONS.md"
preconditions:
  - assert: "status == 'planned'"

3. Atomic CAS Commit and Write-Ahead Log (WAL)

Every ZQL mutation follows the two-phase lifecycle commit pipeline:

  1. Validation & Preconditions: Schema fields, required types, and lifecycle transition constraints are checked against current state.
  2. CAS Ingestion: The serialized object payload is hashed (sha256), written to .zqk/process/<kind>/<hash>.yaml, and the object ID index is updated.
  3. WAL Append: An entry is appended to .zqk/logs/audit/wal.jsonl containing operation metadata, actor attribution, and cryptographic signatures.
  4. Shockwave Emission: Dependent objects (e.g. parent priority plans) receive reactive notification signals to recalculate rolled-up progress metrics.

4. Rollback and Conflict Resolution

If any assertion fails during a multi-object mutation batch:

  • Transaction Abortion: No CAS references are committed.
  • Draft Plane Isolation: Incomplete or draft objects remain sequestered in .zqk/object_drafts/ without polluting the live graph index.
  • Fail-Closed Guarantees: A descriptive error diagnostic is returned, identifying the exact invariant violation.

Canonical References