Release Pack Composition, Object Kind Bindings & Spec Mapping Subsystem Architectural & Operational Guide

1. Executive Summary & Design Philosophy

The Release Pack Composition, Object Kind Bindings & Spec Mapping Subsystem (pkg/releasepack) serves as the core kernel bridge binding release domain object models, lifecycle definitions, and code-generated builder constructors into the unified ZQK composition root.

Within the ZQK Knowledge Kernel, functionality is partitioned into modular domain packs (e.g. workpack, agentpack, pipelinepack, releasepack). Each pack encapsulates its object schemas, lifecycle state transitions, instance builders, and command bindings. The release pack governs the official representation of software version cuts, tracking milestones, backlog deliverables, verification criteria, and release notes:

  • Hermetic Composition Root Integration: Uses blank imports (_) to trigger initialization and registration of instance builders (bldr_instance_v1), lifecycle state machine definitions (bldr_lifecycle_v1), and v2 schema builders (bldr_v2) into the global kernel registry at boot time.
  • Conditional Compilation & Pack Omission: Declares a standardized omission build tag (zqk_omit_releasepack) allowing specialized kernel distributions or minimal agent runtimes to cleanly exclude release domain capabilities without broken imports or compilation errors.
  • Spec & Lifecycle Mapping: Provides deterministic path resolution and verification utilities linking high-level object kinds (release) to their filesystem specifications (packs/release/specs/release.yaml) and state machines (packs/release/lifecycles/release_lifecycle.yaml).
  • Complete Test Coverage & Concurrency Safety: Operates with 100.0% statement test coverage under continuous verification, guaranteeing nil-safe and race-free concurrent execution across multi-agent swarms.

2. Architectural Overview: Release Pack Composition & Object Kind Bindings

In ZQK Core, domain packs act as autonomous plugins that wire themselves into the kernel runtime. Rather than hardcoding domain-specific logic throughout the kernel, the engine relies on self-registering packs that declare owned object kinds, spec locations, and lifecycle hooks.

flowchart TD
    subgraph CompositionRoot["ZQK Composition Root (cmd/zqk / pkg/kernel)"]
        RootBootstrap["Kernel Bootstrap"]
        TagCheck{"zqk_omit_releasepack tag set?"}
        LinkPack["Import pkg/releasepack"]
        OmitPack["Drop from Binary Build"]
    end

    subgraph ReleasePack["Release Pack Subsystem (pkg/releasepack)"]
        PackDef["Pack Constants & Descriptors"]
        KindRegistry["Kinds(): ['release']"]
        PathResolver["SpecPath() / LifecyclePath()"]
        FileVerifier["VerifyFiles() / VerifyPackInRepo()"]
    end

    subgraph GeneratedBuilders["Packs Release Subsystem (packs/release)"]
        BldrInstance["bldr_instance_v1 (ReleaseInstanceBuilder)"]
        BldrLifecycle["bldr_lifecycle_v1 (Release Lifecycle Engine)"]
        BldrV2["bldr_v2 (Release Schema & Field Constants)"]
    end

    subgraph KernelRegistry["Kernel Central Registries"]
        ObjRegistry["Object Registry (pkg/objects)"]
        LifecycleRegistry["Lifecycle Engine (pkg/lifecycle)"]
        BuilderRegistry["Builder Factory Registry"]
    end

    RootBootstrap --> TagCheck
    TagCheck -->|No| LinkPack
    TagCheck -->|Yes| OmitPack

    LinkPack --> PackDef
    PackDef --> KindRegistry
    PackDef --> PathResolver
    PackDef --> FileVerifier

    LinkPack -.->|Blank Import| BldrInstance
    LinkPack -.->|Blank Import| BldrLifecycle
    LinkPack -.->|Blank Import| BldrV2

    BldrInstance -->|"init() register"| BuilderRegistry
    BldrLifecycle -->|"init() register"| LifecycleRegistry
    BldrV2 -->|"init() register"| ObjRegistry

Core Architecture Responsibilities

  1. Self-Describing Topology: pkg/releasepack provides standard package metadata (Name, SpecDir, LifecycleDir, OmitBuildTag, Kinds()), allowing introspective CLI commands (such as zqk pack list or zqk system status) to discover pack properties dynamically.
  2. Deterministic Spec Resolution: Given an execution environment or repository root, the package computes canonical paths to YAML specs and lifecycle definitions, abstracting relative filesystem offsets.
  3. Fail-Closed Verification: At startup, during testing, or in packaging pipelines, VerifyFiles and VerifyPackInRepo ensure that all owned spec and lifecycle files physically exist and are accessible, catching corrupt or incomplete repository structures before runtime execution.

3. Pack Topology & Metadata Model

The release pack encapsulates its configuration in straightforward Go constants and data structures:

const (
    // Name is the pack id the composition root links.
    Name = "release"
    // SpecDir is the object spec directory this pack owns.
    SpecDir = "packs/release/specs"
    // LifecycleDir is the lifecycle directory this pack owns.
    LifecycleDir = "packs/release/lifecycles"
    // OmitBuildTag drops this pack from the zqk composition root.
    OmitBuildTag = "zqk_omit_releasepack"
)

Pack Descriptors & Introspection

The PackInfo struct and Info() accessor provide a JSON-serializable view of the pack's properties:

type PackInfo struct {
    Name         string   `json:"name"`
    SpecDir      string   `json:"spec_dir"`
    LifecycleDir string   `json:"lifecycle_dir"`
    OmitBuildTag string   `json:"omit_build_tag"`
    Kinds        []string `json:"kinds"`
}

func Info() PackInfo {
    return PackInfo{
        Name:         Name,
        SpecDir:      SpecDir,
        LifecycleDir: LifecycleDir,
        OmitBuildTag: OmitBuildTag,
        Kinds:        Kinds(),
    }
}

Object Kind Bindings

The release pack is the sole owner of the release object kind in the knowledge graph:

func Kinds() []string {
    return []string{
        "release",
    }
}

Utility functions HasKind(kind string) bool and ValidateKind(kind string) error allow callers to validate whether an incoming object kind belongs to this pack, returning a sentinel error ErrUnknownKind when unrecognized kinds are passed.


4. Composition Root Integration

The ZQK microkernel follows an inversion-of-control pattern where packages register their capabilities into central registries during Go's package init() phase.

When the composition root (cmd/zqk) imports pkg/releasepack, Go automatically compiles and initializes the referenced subpackages:

import (
    _ "github.com/zqk-os/zqk/packs/release/bldr_instance_v1"
    _ "github.com/zqk-os/zqk/packs/release/bldr_lifecycle_v1"
    _ "github.com/zqk-os/zqk/packs/release/bldr_v2"
)
sequenceDiagram
    autonumber
    participant CLI as ZQK CLI Composition Root (cmd/zqk)
    participant RP as pkg/releasepack
    participant BI as packs/release/bldr_instance_v1
    participant BL as packs/release/bldr_lifecycle_v1
    participant BV as packs/release/bldr_v2
    participant KR as Kernel Registries

    CLI->>RP: Blank import pkg/releasepack
    RP->>BI: Initialize bldr_instance_v1
    BI->>KR: Register ReleaseInstanceBuilder
    RP->>BL: Initialize bldr_lifecycle_v1
    BL->>KR: Register Release Lifecycle State Machine
    RP->>BV: Initialize bldr_v2
    BV->>KR: Register Release V2 Builder & Schema Constants
    CLI->>RP: Query Pack Info (Info(), Kinds())
    RP-->>CLI: Return PackInfo metadata

Selective Inclusion via Build Tags

In resource-constrained deployments, edge agents, or specialized micro-daemons, the release pack can be omitted at compile time by passing the build tag:

go build -tags zqk_omit_releasepack ./cmd/zqk

When this tag is specified, the composition root excludes pkg/releasepack, omitting the release builders and lifecycle definitions from the resulting executable and reducing binary footprint.


5. Release Object Lifecycle & Verification

The release object represents a planned or completed version cut of a software system. Its lifecycle state machine ensures that releases undergo strict progression from proposal through planning, cutting, and publication.

stateDiagram-v2
    [*] --> Conceptual: Draft Plane (pre-CAS)
    Conceptual --> Originated: Membrane Crossed
    Originated --> Planned: Version & Schedule Locked
    Planned --> InProgress: Cutting Release (Notes & Contents Moving)
    InProgress --> Released: Shipped & Cryptographically Sealed
    Released --> [*]: Terminal State

    Originated --> Abandoned: Dropped before Cut
    Planned --> Abandoned: Dropped before Cut
    InProgress --> Abandoned: Failed / Superseded

Lifecycle States and Roles

State Role Description
conceptual realign Draft plane state prior to Content-Addressable Storage (CAS) membrane crossing.
originated realign CAS membrane crossed. Object officially minted and tracked in the knowledge graph.
planned shovel_ready Release version and target date are established. Work is queued.
in_progress execution_locked Release cut underway. Backlog item references, notes, and criteria are being finalized.
released completed Release cut is finalized, checksums generated, and artifacts published.
abandoned archived Release cancelled or superseded. Retained for historical auditability.

Schema Verification & Integrity

The release object specification (packs/release/specs/release.yaml) defines mandatory attributes, reference associations, and security profiles:

  • version: Semantic version identifier (e.g. v1.24.0).
  • release_date: ISO-8601 release timestamp.
  • release_type: Major, minor, patch, or release-candidate classification.
  • milestone_refs: Associated milestone anchors.
  • backlog_item_refs: Backlog items delivered in this release.
  • criteria_refs: Quality and acceptance criteria verified for release readiness.
  • release_notes: Markdown release documentation and changelog.

pkg/releasepack provides runtime verification functions:

  • SpecPath(baseDir, kind string) (string, error): Returns absolute or relative path to the YAML specification.
  • LifecyclePath(baseDir, kind string) (string, error): Returns path to the lifecycle state machine file.
  • VerifyKindFiles(baseDir string, kinds []string) error: Confirms that both spec and lifecycle definitions are present on disk.
  • VerifyFiles(baseDir string) error: Convenience check running verification against all kinds owned by the pack.
  • ResolveModuleRoot(startDir string) (string, error): Walks upwards from the given directory to locate the repository root containing go.mod.
  • VerifyPackInRepo(startDir string) error: Discovers the module root and validates the complete pack layout.

6. Testing, Verification & Coverage Invariant

The subsystem enforces a strict test coverage invariant (statement coverage strictly >= 85.0%, with full target of 100.0%).

flowchart TD
    TestStart["go test -cover ./pkg/releasepack"]
    T1["TestConstantsAndPackInfo: Metadata integrity"]
    T2["TestKindsAndHasKind: Membership checks"]
    T3["TestValidateKind: Known vs Unknown kinds"]
    T4["TestSpecPath: Relative & Absolute paths"]
    T5["TestLifecyclePath: Lifecycle paths"]
    T6["TestVerifyKindFiles: Missing specs & lifecycles"]
    T7["TestVerifyFiles: Repo check & empty dir failure"]
    T8["TestResolveModuleRoot: Traversal & error mocking"]
    T9["TestVerifyPackInRepo: Full repository validation"]
    T10["TestConcurrencySafety: Parallel goroutines (race-free)"]

    TestStart --> T1 --> T2 --> T3 --> T4 --> T5
    T5 --> T6 --> T7 --> T8 --> T9 --> T10
    T10 --> AssertCov{"Coverage == 100.0%?"}
    AssertCov -->|Pass| Success["Gate Passed (100.0% Coverage)"]
    AssertCov -->|Fail| Fail["Gate Rejected (Coverage < 85.0%)"]

Running Targeted Tests

To run the release pack test suite in isolation:

ZQK_ALLOW_FOREGROUND_GO_TEST=1 go test -v -timeout 30s -cover ./pkg/releasepack

All test cases are implemented in releasepack_coverage_elevation_cycle198_test.go, licensed under Apache-2.0, with zero swallowed errors and complete error branch assertion.


7. Operational Recipes & Developer Reference

Inspecting Pack Information Programmatically

package main

import (
    "fmt"
    "github.com/zqk-os/zqk/pkg/releasepack"
)

func main() {
    info := releasepack.Info()
    fmt.Printf("Pack: %s\n", info.Name)
    fmt.Printf("Spec Dir: %s\n", info.SpecDir)
    fmt.Printf("Lifecycle Dir: %s\n", info.LifecycleDir)
    fmt.Printf("Kinds: %v\n", info.Kinds)

    if releasepack.HasKind("release") {
        specPath, err := releasepack.SpecPath("", "release")
        if err != nil {
            panic(err)
        }
        fmt.Printf("Release spec path: %s\n", specPath)
    }
}

Verifying Pack Integrity in Custom Workspaces

package main

import (
    "fmt"
    "github.com/zqk-os/zqk/pkg/releasepack"
)

func verifyWorkspace(wsPath string) error {
    if err := releasepack.VerifyFiles(wsPath); err != nil {
        return fmt.Errorf("workspace release pack verification failed: %w", err)
    }
    return nil
}

Registering Custom Object Validations

When writing admission webhooks or git pre-commit hooks, use ValidateKind:

func ValidateCommitObject(kind string) error {
    if !releasepack.HasKind(kind) {
        return fmt.Errorf("kind %q not handled by release pack", kind)
    }
    return nil
}