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, or zqk-dev) must not break environment variable resolution (e.g., config should still read canonical ZQK_* rather than fracturing into ZQK_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>.test or main inside 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:

  1. Path Normalization: Extracts the binary base name using filepath.Base and strips Windows .exe suffixes case-insensitively.
  2. Go Test & Build Directory Rejection: If the executable ends with .test, equals main or main.exe, or originates from a temporary Go build path (go-build or ___go_build), it is immediately rejected, reverting safely to the default canonical name ("zqk").
  3. 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:

  1. config/zqk.yaml: Version-controlled base project configuration.
  2. 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.