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
- Self-Describing Topology:
pkg/releasepackprovides standard package metadata (Name,SpecDir,LifecycleDir,OmitBuildTag,Kinds()), allowing introspective CLI commands (such aszqk pack listorzqk system status) to discover pack properties dynamically. - 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.
- Fail-Closed Verification: At startup, during testing, or in packaging pipelines,
VerifyFilesandVerifyPackInRepoensure 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 containinggo.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
}