Branding & Identity Subsystem Architectural & Operational Guide
Comprehensive architectural manual, executable identity discovery specification, and operational guide for the ZQK Branding & Runtime Subsystem (pkg/brand).
1. Overview & Architectural Compass
The Branding & Identity Subsystem (pkg/brand) provides centralized executable name resolution, product identity derivation, environment variable namespace binding, and channel suffix management for the Zen Quantum Knowledge Kernel.
In an enterprise-grade, extensible operating kernel, hardcoded binary names (zqk) and static environment variable prefixes (ZQK_) present significant architectural liabilities:
- White-Label & Forking Rigidity: Downstream enterprise distributions, private forks, and specialized appliance builds require dynamic rebranding without patching hundreds of source files.
- Packaging & Channel Divergence: Running channel-specific binaries (such as
zqk-stable,zqk-community, orzqk-dev) must not break environment variable resolution (e.g., config should still read canonicalZQK_*rather than fracturing intoZQK_STABLE_*). - Daemon & Subsystem Multiplexing: Background services (Ambient daemons, CAP loop schedulers, Privileged Writers, Process Overseers, and MCP adapters) must follow deterministic naming conventions (
<brand>-sched,<brand>-amb,<brand>-pw,<brand>-mcp-daemon) while retaining automatic fallback to upstream canonical binaries. - Test Harness Contamination: When running tests via
go test, the execution binary is compiled as a temporary test executable (<pkg>.testormaininside temporary build caches). Unaware identity resolution would misidentify the test runner as the CLI product, triggering catastrophic self-execution loops (fork-bombs) during subagent orchestration and MCP tool invocation.
The pkg/brand subsystem eliminates these failure modes through lock-free atomic registries, deterministic executable inspection, robust channel stripping algorithms, and clean project-level configuration cascades.
flowchart TD
subgraph HostEnvironment["Host Runtime & Process Environment"]
Args["os.Args[0] (Binary Path)"]
ConfigFiles["config/zqk.yaml & config/zqk-local.yaml"]
EnvContext["Environment Key Lookups"]
end
subgraph BrandSubsystem["pkg/brand Subsystem"]
subgraph Inspector["Executable Inspector & Normalizer"]
ArgInspector["Executable Inspector (filepath.Base & .exe Stripping)"]
TestFilter["Test & Harness Filter (*.test, main, go-build)"]
ChannelFilter["Channel Suffix Stripper (-stable, -sched, -amb, -dev)"]
end
subgraph Registry["Lock-Free Brand Registry"]
ExeAtomic["atomic.Value: ExecutableName"]
ProdAtomic["atomic.Value: ProductName"]
NSAtomic["atomic.Value: NamespacePrefix"]
end
subgraph Resolvers["Identity & Configuration Resolvers"]
EnvResolver["Environment Variable Resolver (EnvPrefix & EnvVar)"]
RoleDecorator["Role Differentiator Decorator (RoleDifferentiatorNames)"]
ConfigLoader["Project Config Loader (LoadFromProject)"]
end
end
subgraph Consumers["Kernel Consumers & Workflows"]
MCP["MCP Server & Tool Registry"]
Daemons["Background Daemons (Sched, Amb, PW, Overseer)"]
AgentSwarm["Subagent Runner & CAP Flywheel"]
CLIApp["CLI App & Help Display"]
end
Args --> ArgInspector
ArgInspector --> TestFilter
TestFilter --> ChannelFilter
ChannelFilter --> ExeAtomic
ConfigFiles --> ConfigLoader
ConfigLoader --> Registry
ExeAtomic --> Resolvers
ProdAtomic --> Resolvers
NSAtomic --> Resolvers
Resolvers --> Consumers
2. Component Topology & Architecture
The pkg/brand package is divided into core functional facets:
2.1 Brand Registry & State Storage
The subsystem maintains process-wide branding attributes using sync/atomic.Value instances. This design ensures that brand lookups on hot execution paths remain entirely non-blocking and thread-safe without mutex contention:
var (
executableName atomic.Value // string
productName atomic.Value // string
namespacePrefix atomic.Value // string
)
ExecutableName(): Returns the resolved binary name (default:"zqk"). Used across CLI help text, subagent execution commands, and external process spawning.ProductName(): Returns the human-readable product display name (default:"ZQK"). Used in banners, status logs, and UI presentation.NamespacePrefix(): Returns the canonical kernel namespace identifier (default:"zqk"). Used for MCP tool registration prefixes and internal graph scope identifiers.
2.2 Executable Inspector & Test Filter
The executable inspector examines os.Args[0] to automatically detect the running binary identity while filtering out ephemeral test binaries:
- Path Normalization: Extracts the binary base name using
filepath.Baseand strips Windows.exesuffixes case-insensitively. - Go Test & Build Directory Rejection: If the executable ends with
.test, equalsmainormain.exe, or originates from a temporary Go build path (go-buildor___go_build), it is immediately rejected, reverting safely to the default canonical name ("zqk"). - Channel & Role Normalization: Strips packaged role suffixes (such as
zqk-pw,zqk-amb,zqk-sched,zqk-overseer) or channel identifiers (zqk-stable,zqk-stable-*) to establish the root brand identity.
2.3 Channel & Packaging Suffix Stripper
The stripEnvChannelSuffix routine enforces an ordered priority list of packaging and role suffixes. Longer, more specific suffixes are evaluated first to prevent partial truncation:
| Suffix Category | Suffixes Evaluated (Ordered) | Result Transformation |
|---|---|---|
| Test Runner | .test |
pkg.test → pkg |
| MCP Adapters | -mcp-ide-adapter, -mcp-proxy, -mcp-daemon, -mcp |
zqk-mcp-daemon → zqk |
| Privileged Services | -privileged-writer, -pw |
acme-privileged-writer → acme |
| Ambient Daemons | -ambient-daemon, -ambient, -amb |
custom-amb → custom |
| Scheduler Daemons | -scheduler-daemon, -scheduler, -sched |
foo-scheduler → foo |
| Overseer Service | -overseer |
bar-overseer → bar |
| Release Channels | -community, -stable, -dev, -beta, -alpha, -rc |
zqk-stable → zqk |
2.4 Environment Variable Resolver
The environment resolver (EnvPrefix, EnvPrefixForExecutable, and EnvVar) translates arbitrary brand executable names into uppercase, POSIX-compliant environment variable prefixes:
- Non-alphanumeric characters (hyphens, spaces, dots) are converted into underscores.
- Consecutive underscores are collapsed into a single underscore.
- Leading and trailing underscores are stripped.
- Channel suffixes are stripped prior to conversion so that release channel variants share identical environment configurations.
Executable: "acme-corp-cli-stable"
-> Channel Stripped: "acme-corp-cli"
-> Character Mapping: "ACME_CORP_CLI"
-> EnvVar("PORT"): "ACME_CORP_CLI_PORT"
2.5 Role Differentiator Decorator
Daemons and worker processes in the ZQK cluster require specific binary names depending on whether the system is running under the upstream canonical brand or a branded fork.
RoleDifferentiatorNames(role) generates candidate binary basenames in priority order:
- Under custom brand
"acme", candidate daemon binaries for role"sched"will be["acme-sched", "acme-scheduler", "zqk-sched", "zqk-scheduler"]. - Under default brand
"zqk", candidate daemon binaries will be["zqk-sched", "zqk-scheduler"].
This dynamic priority chain guarantees backward compatibility with upstream infrastructure while enabling clean white-label deployments.
3. Executable & Channel Resolution Lifecycle
The following sequence illustrates how the runtime resolves brand identity, applies project overrides, and binds environment variables during bootstrap:
sequenceDiagram
autonumber
participant Runtime as Process Main (cmd/zqk)
participant Brand as pkg/brand
participant FS as Workspace Config
participant Env as Environment Store
Runtime->>Brand: init()
Brand->>Brand: defaultExecutableName() inspects os.Args[0]
Brand->>Brand: Filter *.test, main, go-build artifacts
Brand->>Brand: stripEnvChannelSuffix()
Brand-->>Runtime: Initial Defaults Loaded (zqk, ZQK, zqk)
Runtime->>FS: LoadFromProject(workspaceRoot)
FS-->>Brand: Read config/zqk.yaml & config/zqk-local.yaml
opt Overrides Present in Config
Brand->>Brand: SetExecutableName(cfg.ExecutableName)
Brand->>Brand: SetProductName(cfg.ProductName)
Brand->>Brand: SetNamespacePrefix(cfg.NamespacePrefix)
end
Runtime->>Env: EnvVar("CONFIG_PATH")
Env->>Brand: EnvPrefix()
Brand-->>Env: "ZQK" (or custom "ACME")
Env-->>Runtime: Returns "ZQK_CONFIG_PATH" (or "ACME_CONFIG_PATH")
4. Multi-Tenant & White-Label Isolation
4.1 Namespace Prefix Normalization
MCP (Model Context Protocol) tool names and internal schema identifiers must remain deterministic even when invoked through channel binaries.
If an operator launches a subagent using zqk-stable, the tool namespace must not mutate into zqk-stable_* (which would invalidate client tool schemas). ProductNamespacePrefix(prefix) normalizes channel binaries and administration roles:
// Both map deterministically to "zqk"
ProductNamespacePrefix("zqk") // "zqk"
ProductNamespacePrefix("zqk-stable") // "zqk"
ProductNamespacePrefix("zqk-admin") // "zqk"
4.2 Configuration File Hierarchy
When customizing brand identity per project or deployment environment, the kernel reads two hierarchical configuration files:
config/zqk.yaml: Version-controlled base project configuration.config/zqk-local.yaml: Unversioned local developer/operator override file (takes precedence).
# config/zqk.yaml
brand:
executable_name: "acme-kernel"
product_name: "Acme Operating Kernel"
namespace_prefix: "acme"
LoadFromProject(root) gracefully handles missing files, unreadable permissions, or corrupt YAML structures by falling back to compiled upstream defaults without crashing.
5. Operational Recipes & Code Patterns
5.1 Querying Brand Identity in Subsystems
Subsystems should never hardcode "ZQK" or "zqk". Always use dynamic brand queries:
package mysubsystem
import (
"fmt"
"os"
"github.com/zqk-os/zqk/pkg/brand"
)
func BuildDaemonCommand() string {
// Resolves to "zqk-sched" or "<brand>-sched"
binary := brand.SchedExecutableName()
return fmt.Sprintf("%s start", binary)
}
func LookupPort() string {
// Looks up "ZQK_PORT" or "<BRAND>_PORT"
key := brand.EnvVar("PORT")
if val := os.Getenv(key); val != "" {
return val
}
return "8080"
}
5.2 Unit Testing with Isolated Brand Overrides
When writing unit tests that temporarily alter brand configuration, always save previous state and restore it via t.Cleanup:
func TestCustomBrandFeature(t *testing.T) {
origExe := brand.ExecutableName()
origProd := brand.ProductName()
origNS := brand.NamespacePrefix()
t.Cleanup(func() {
brand.SetExecutableName(origExe)
brand.SetProductName(origProd)
brand.SetNamespacePrefix(origNS)
})
brand.SetExecutableName("acmectl")
brand.SetProductName("AcmeControl")
brand.SetNamespacePrefix("acmectl")
if got := brand.EnvVar("API_KEY"); got != "ACMECTL_API_KEY" {
t.Fatalf("unexpected env var: %s", got)
}
}
6. Verification & Test Coverage Invariant
The pkg/brand subsystem is governed by a strict Static Floor Invariant requiring statement test coverage to be maintained at or above 85.0%.
6.1 Running Scoped Verification
To verify statement test coverage and execute all unit tests within the package:
ZQK_ALLOW_FOREGROUND_GO_TEST=1 go test -v -timeout 30s -cover ./pkg/brand
6.2 Verifying Code Profile Coverage
To generate and inspect a per-function statement coverage report:
ZQK_ALLOW_FOREGROUND_GO_TEST=1 go test -timeout 30s -coverprofile=coverage.out ./pkg/brand
go tool cover -func=coverage.out
All functions across env.go and runtime.go are verified with 100% statement coverage.