CLI Domain Subsystem & Ontology Registration Guide

Overview

The ZQK Domain Subsystem (cmd/zqk/domain) provides discovery and registration capabilities for extensible domain ontologies within the Zen Quantum Kernel. While the core kernel manages universal lifecycle primitives (such as goals, requirements, criteria, test cases, and backlog items), real-world systems require domain-specific bounded contexts, entity definitions, and vocabulary namespaces.

The domain subsystem decouples vertical application domains from the core kernel engine by managing domain_registry objects in the Content Addressable Storage (CAS). This ensures that custom domain models, specifications, and namespace boundaries remain queryable, verifiable, and versioned within the knowledge graph.

Core Capabilities

  1. Domain Discovery (zqk domain discover): - Queries and enumerates all active domain registry objects (domain_registry). - Surfaces domain identifier mappings, titles, and attached bounded contexts. - Provides clear onboarding recommendations when no registries are present.

  2. Domain Registration (zqk domain register): - Validates domain identifiers, target namespaces, and specification files. - Automatically initializes sequential domain registry containers (DOMAIN-REG-001, DOMAIN-REG-002, etc.) when empty. - Appends new domain definitions safely into existing registry containers without data loss or race conditions. - Provides a zero-mutation --dry-run preview mode for validation before state mutation.


Architectural Taxonomy & Component Layout

cmd/zqk/domain/
├── domain.go                               # Root 'domain' command definition & storage listing helpers
├── discover.go                             # 'domain discover' command implementation & formatter
├── register.go                             # 'domain register' command, flag bindings, & sequential ID generator
├── domain_coverage_elevation_test.go       # High-coverage unit tests, error injection & flag matrix
├── domain_integration_test.go              # Storage integration tests & multi-entry lifecycle tests
└── domain_test_layout_helpers_test.go      # Test fixture layout builders & stdout capture utilities

Command Hierarchy

zqk
└── domain                                  # Domain ontology discovery and registration
    ├── discover                            # Discover registered domain ontologies
    └── register                            # Register a domain ontology with namespace and spec

1. Discovering Registered Domain Ontologies (zqk domain discover)

The discover command scans the CAS for domain_registry objects and prints an inventory of registered domains and their associated titles.

Command Usage

zqk domain discover

Output Formats

Empty State

When no domain registries exist in the active project:

No domain registries found.
Use 'zqk object create domain_registry --file <yaml>' to register a domain.

Populated State

When one or more domain registries are stored:

Discovered 2 domain registr(y/ies):
  - DOMAIN-REG-001 (Primary Enterprise Domain Registry)
  - DOMAIN-REG-002 (Telemetry & Analytics Ontology)

2. Registering Domain Ontologies (zqk domain register)

The register command creates or updates a domain registration entry. It supports defining custom namespace patterns and linking external YAML specification files.

Command Syntax

zqk domain register --domain-id <id> [flags]

Supported Flags

Flag Type Required Default Description
--domain-id string Yes "" Unique identifier for the domain being registered.
--namespace string No "" Target namespace pattern for domain objects (e.g., ecommerce:orders:*).
--spec-file string No "" Relative or absolute path to the YAML specification file describing the domain ontology.
--dry-run bool No false Preview registration changes without mutating kernel storage or creating registry objects.

Operational Examples

Basic Registration

Register a minimal domain with only an identifier:

zqk domain register --domain-id billing

Output:

Domain registered: billing
Registry: DOMAIN-REG-001

Full Registration with Namespace and Specification

Register a domain with an explicit namespace constraint and a specification schema:

zqk domain register \
  --domain-id logistics \
  --namespace "logistics:shipping:*" \
  --spec-file "specs/logistics_ontology.yaml"

Output:

Domain registered: logistics
Registry: DOMAIN-REG-001

Dry-Run Preview

Validate domain parameters without modifying persistent storage:

zqk domain register \
  --domain-id telemetry \
  --namespace "telemetry:events:*" \
  --spec-file "specs/telemetry.yaml" \
  --dry-run

Output:

Dry run: would register domain "telemetry" (namespace="telemetry:events:*", spec-file="specs/telemetry.yaml")

3. Knowledge Kernel Object Model: domain_registry

Domain registrations are persisted as structured YAML objects under .zqk/process/domain_registry/ conforming to the ZQK CAS schema:

id: DOMAIN-REG-001
kind: domain_registry
title: Domain registry
status: active
schema_version: 2.0.0
domains:
  - id: billing
  - id: logistics
    namespace: logistics:shipping:*
    spec_file: specs/logistics_ontology.yaml

Lifecycle & Persistence Characteristics

  1. Sequential Identification (DOMAIN-REG-%03d): - The registry identifier uses monotonic sequential formatting regex ^DOMAIN-REG-(\d+)$. - When the first domain is registered, DOMAIN-REG-001 is allocated.
  2. Atomic In-Memory & Storage Append: - Subsequent calls to zqk domain register inspect existing registries and append domain entries directly into the domains array. - Mutations trigger memory cache invalidation via pkgctx.WithCacheUpdate, ensuring immediate consistency across concurrent CLI commands.
  3. Fail-Closed Input Validation: - Omitting --domain-id immediately aborts with --domain-id is required before any storage interaction or transaction initialization.

4. Verification and Done-Gate Matrix

Criterion ID Category Description Verification Method
CRIT-001 Acceptance cmd/zqk/domain achieves \(\ge 80.0\%\) statement coverage and validates CLI command hierarchy go test -short -cover ./cmd/zqk/domain
CRIT-001 Functional Boundary condition validation, error paths (storage list/create/update failures), and dry-run preview cmd/zqk/domain/domain_coverage_elevation_test.go
CRIT-001 Compliance Comprehensive documentation guide authored and committed docs/guides/CLI_DOMAIN_SUBSYSTEM_AND_ONTOLOGY_REGISTRATION_GUIDE.md