CLI Knowledge Graph & State Engine Guide

Executive Overview

The ZQK Knowledge Kernel provides two complementary lenses into system structure and temporal evolution:

  1. Knowledge Graph Subsystem (zqk graph): Structural exploration, pattern matching, dependency traversal, and multi-format topological export across all kernel entities.
  2. Real-Time State Engine Subsystem (zqk state): Dynamic runtime introspection, hierarchical tree projection, time-series telemetry (TSDB), and real-time streaming seismograph tracking mutations across the event membrane.

1. Knowledge Graph Subsystem (zqk graph)

The Knowledge Graph treats all persistent kernel objects (Goals, Milestones, Priority Plans, Requirements, Backlog Items, Technical Debt, Policies) as nodes, interconnected by typed, directed edges derived from relational references (goal_refs, priority_plan_ref, requirement_refs, epic_refs, criteria_refs).

flowchart TD
    G[Goal: Strategic Compass] -->|goal_refs| E[Epic: Domain Umbrella]
    E -->|epic_refs| P[Priority Plan: 1-Cycle Batch]
    P -->|priority_plan_ref| B[Backlog Item: Atomic Effort]
    G -->|goal_refs| R[Requirement: Feature Contract]
    R -->|criteria_refs| C[Criteria: 3-Fold Proof]
    B -->|requirement_refs| R

Commands & Capabilities

1.1 zqk graph query

Executes declarative pattern matching queries across the in-memory or persisted graph:

  • Usage: zqk graph query --type <kind> [flags]
  • Supported Options:
  • --type <kind>: Object kind to query (e.g. backlog_item, requirement, goal).
  • --status <status>: Filter nodes by lifecycle status (originated, in_progress, complete).
  • --format json|table: Output projection format.

1.2 zqk graph discover

Traces outgoing and incoming edges recursively from a starting node root:

  • Usage: zqk graph discover --root <id> [flags]
  • Key Options:
  • --root <ID>: Target entity ID (e.g., PRI-001).
  • --depth <int>: Traversal recursion limit (default: 3).
  • --direction <outbound|inbound|both>: Direction of relational references to follow.
  • --format <text|json>: Human-readable tree vs machine-parseable JSON AST.

1.3 zqk graph export

Exports graph topology for external visualization and verification engines:

  • Usage: zqk graph export --format <format> [--out <file>]
  • Supported Formats:
  • json: Standard JSON node/edge dictionary.
  • graphml: XML-based GraphML format for yEd, Gephi, and Cytoscape.
  • cytoscape: Cytoscape.js compatible schema ({ nodes: [...], edges: [...] }).
  • databook: W3C Holon DataBook JSON-LD schema with @context semantic metadata.

2. Real-Time State Engine Subsystem (zqk state)

The State Engine exposes runtime execution vitals, chronologically ordered stream journals, and resource health metrics.

Commands & Capabilities

2.1 zqk state tree

Renders the complete 5-layer cascade of the active workspace:

📍 ZQK Knowledge Kernel State Tree
├── Organization: Default Organization [ORG-DEFAULT]
│   └── Mission: Core Mission [MIS-001]
│       └── Vision: System Vision [VIS-001]
│           └── Goal: System Quality [GOAL-001]
│               └── Plan: Storage Elevation [PLAN-001] (in_progress)
│                   └── Requirement: Conformance [REQ-001]
│                       └── Work Item: Implement Tests [ITEM-001] (in_progress)
  • Available in human-readable tree text or structured JSON (--format json).

2.2 zqk state journal

Scans and displays chronologically ordered change journal mutations (change_journal_entry):

  • Usage: zqk state journal [--limit 20] [--format table|json]
  • Shows timestamp, change type (CREATE, UPDATE, PROMOTE, DELETE), target object reference, and human-readable diff summaries.

2.3 zqk state stream

Watches the kernel event seismograph with live streaming updates:

  • Usage: zqk state stream [--follow] [--dashboard]
  • Standard output renders real-time mutation events with CPCP membrane verification badges:
  • [CPCP: PASS]: Invariant proof verified fail-closed.
  • [CPCP: FAIL]: Membrane boundary violation intercepted.
  • --dashboard activates the curses-style split dashboard with event window rate sparklines ([ ▂▂▂▂▃]) and actor velocity counts.

2.4 zqk state tsdb

Queries the kernel's embedded Time-Series Database (TSDB) and metrics store:

  • System Vitals: File descriptor consumption vs ulimit, disk storage bytes, stale lock detection.
  • CAS Object Volumes: Distribution of objects by kind across content-addressable storage.
  • Ingestion Velocity: Stream file accumulation rates.
  • CLI Velocity: Top invoked commands, average duration, failure rate.
  • Scheduler Performance Matrix: Job execution duration minimum, maximum, average latency, and historical sparkline trend.

3. Verification & Test Coverage Matrix

Both subsystems maintain \(\ge 80.0\%\) statement test coverage enforced via automated unit test suites:

Package Statement Coverage Test Files Primary Focus Areas
cmd/zqk/graph 81.5% graph_test.go, graph_extended_test.go Graph discovery traversal, root expansion, Cypher query projection, GraphML / Cytoscape / DataBook export
cmd/zqk/state 83.3% tree_test.go, tsdb_test.go, stream_test.go, state_extended_test.go Tree hierarchy projection, TSDB metrics unmarshaling, stream seismograph tailing, dashboard rendering

4. Operational Troubleshooting

  • Stale Index / Cache Invalidation: Run zqk system check --auto-remedy to clear stale locks and resynchronize CAS index mappings.
  • High Memory or File Descriptor Spikes: Run zqk state tsdb --since 1h to inspect FD usage percent and identify commands experiencing unbounded resource allocation.
  • Stream Ingestion Backlog: Run zqk state journal --limit 50 to inspect recent mutations for stuck transactions or uncommitted leases.