Cellular Specialization Tiers (pkg/specialization)
pkg/specialization governs horizontal node segregation, component filtering, and side-effect sandboxing within ZQK swarm deployments.
1. Concept: The Biological Analogy
Rather than monolithic clustering where every node runs every daemon, ZQK allows nodes to specialize into biological organ roles:
┌────────────────────────────────────────┐
│ ZQK Swarm Organism │
└───────────────────┬────────────────────┘
│
┌───────────────────┬─────────────┴─────┬───────────────────┐
▼ ▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ TierNeuron │ │ TierMuscle │ │ TierHeart │ │ TierLung │
├──────────────┤ ├──────────────┤ ├──────────────┤ ├──────────────┤
│ - Inference │ │ - Execution │ │ - Vitality │ │ - Mesh P2P │
│ - Reconciler │ │ - Scheduler │ │ - Telemetry │ │ - Peering │
│ - Assessor │ │ - Importer │ │ - Health │ │ - Federation │
│ - Semantics │ │ - Docman │ │ - Retention │ │ - Transport │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
By default in local single-machine and community setups, the tier is TierAll ("all"), meaning the single node orchestrates all components concurrently.
2. Specialization Tiers
| Tier | Value | Designated Components | Purpose |
|---|---|---|---|
| All | "all" |
All components | Monolithic single-node mode (default developer & community setup). |
| Neuron | "neuron" |
reconciler, assessor, inference |
High-memory, GPU/LLM-adjacent compute focused on reasoning and state reconciliation. |
| Muscle | "muscle" |
scheduler, importer, docman |
High-CPU compute responsible for running scheduled jobs, building artifacts, and executing tasks. |
| Heart | "heart" |
metrics, health |
Low-latency monitoring node tracking process vitality, CAS integrity, and audit aggregation. |
| Lung | "lung" |
mesh, federation |
Gateway nodes managing inter-cluster transport, peer gossip, and packet routing. |
3. Operational Modes: Normal vs Shielded (Rubber Room)
ModeNormal("normal"): Standard mode where mutations and state transitions commit directly to the primary storage spine.ModeShielded("shielded"): Sandboxed mode running within a ShadowSpine ("Rubber Room"). Side-effects, disk writes, and mutations are isolated from the production kernel graph, enabling safe execution of untrusted code, exploratory simulations, and fuzzing passes.
4. Configuration
The active tier is configured via environment variable ZQK_SPECIALIZATION_TIER (or baked into the binary at link time via -ldflags "-X github.com/zqk-os/zqk/pkg/specialization.DefaultTier=neuron"):
# Run node as a dedicated execution muscle
export ZQK_SPECIALIZATION_TIER=muscle
zqk scheduler daemon