ZQK Knowledge Kernel Architecture Index
Welcome to the architectural specifications and design documents for the ZQK Knowledge Operating System (KOS). This index categorizes all core design documents, invariants, threat models, and subsystem specifications.
1. Storage & Membrane Architecture
Documents governing Content-Addressable Storage (CAS), append-only WAL streams, memory isolation, and privileged filesystem access.
- Cellular Membrane Mode B Configuration: Mode A (developer standalone) vs Mode B (cellular membrane lockdown with isolated
PrivilegedWriterDaemonand UNIX domain socket IPC). - Cellular Specialization Tiers & Rubber Room: Biological organ specialization tiers (
Neuron,Muscle,Heart,Lung) and sandboxed side-effect execution in the Rubber Room (ModeShielded/ShadowSpine). - Tiered Storage and Archival Lifecycle: Three-tier storage hierarchy: hot active CAS, warm index layers, and cold compressed stream archives.
- Storage Write Queue & Observer Governance: Non-blocking asynchronous event queues, observer fan-out, and memory hygiene.
- Project-Scoped Reverse Reference Index: Caching and reverse referencing mechanisms.
2. Mutation & Data Integrity Governance
Documents governing state transitions, provenance enforcement, and fail-closed validation.
- Membrane Mutation Governance & Integrity Specification: System provenance fields (
created_at,cas_address,hash), directed state graph transitions, audited--overrideelevation, and interactive TTY friction controls. - Lifecycle State Machine Architecture: Formal lifecycle definitions, state transitions, and precondition verification engines.
- Verifiable Decomposition Spine (VDS): Done-gates, requirement-to-criteria traceability cascades, Definition of Done enforcement, and three-fold proof invariants.
- Fail-Closed Error Propagation: Core error handling and propagation strategy.
- Fail-Closed Error Propagation & Transaction Resilience: Fail-closed boundary guarantees across storage, networking, and validation boundaries.
- Fail-Closed Panic Resilience: Subprocess and thread isolation preventing daemon crashes and unhandled panic propagation.
3. CLI Command Taxonomy & Ergonomics
Documents governing the Cobra CLI command surface, taxonomy standards, builders, and verb mappings.
- CLI Command Taxonomy Standards: Canonical noun-verb command standards, grammar rules, YAML specification inventory, and regression guardrails.
- Polyglot AST Code Search Architecture & Roadmap (
zqk grep): In-process trigram and polyglot AST code search engine with strict token budgeting. - Orphan Verbs Retirement & Canonical Domain Mapping: Ergonomic root shortcuts (
zqk do,zqk inspect,zqk mutate) mapped to canonical domain commands (zqk workflow do,zqk object inspect, etc.). - Acronym Vocabulary Scheme & Progressive Disclosure: Glossary scheme for technical acronyms (CAS, VDS, DoD, BLI, REQ, CRIT) and cognitive load management.
- Diagnostics Auto Remedy: Ergonomic flows for diagnosing and fixing issues.
- Worktree Kernel Resolution: Resolving kernel locations within git worktrees.
- ZQK Do Autonomous Execution: Guidelines for the
zqk docapability.
4. Daemons, Schedulers & Concurrency
Documents governing persistent host processes, background watchers, and job concurrency.
- Daemon Singleton Mutual Exclusion: Cross-platform PID lock acquisition, single-instance enforcement, and automatic recovery of dead daemon leases.
- Seat Worker Supervisor Architecture: OS-level supervisor daemons (
launchdon macOS,systemdon Linux) managing persistent 24/7 background agent seats. - Ambient Signal Action Rubric: Ambient filesystem watcher events, heuristics evaluation, and proactive maintenance signals.
- Async Check Discovery Decoupling: Decoupling disk discovery from validation pipelines to prevent CLI timeout stalls.
- Service Adapter Specification: Unified abstraction across macOS
launchd, Linuxsystemd, and standalone foreground runners. - Zero-Copy Shared-Memory IPC and Vectorized Batch Delivery: Zero-copy memory-mapped ring buffers, lock-free MPMC queue sequencing, cache-line isolation, and vectorized callback delivery.
- Universal Model Gradient Router & Scheduler Write-Through Cache Architecture: In-memory write-through cache with file mtime invalidation, known-idle job tracking, Win32 native mmap, and adaptive gradient tool routing.
- Dynamic Subscriber Topology Partitioning & Work-Stealing: Virtual-node consistent hash rings, Chase-Lev work-stealing deques, and lossless dynamic shard rebalancing across event mesh subscribers.
- Dynamic Subscriber Topology Work-Stealing Specification: Complete topological specification for subscriber work stealing and partition mapping.
- Distributed Gossip Membership and Peer Failure Detector: SWIM protocol implementation with indirect probing, suspicion timers, incarnation monotonicity, and self-healing cluster recovery.
- Distributed Dead-Letter Queue (DLQ), Poison Pill Quarantine, and Automated Event Redrive Engine: Tamper-evident QuarantineEnvelope cryptographic checksums, PoisonPillQuarantine isolation vaults, and automated redrive with exponential backoff and jitter.
- Adaptive Backoff Exponential Jitter and Quorum Damping: Decorrelated exponential jitter backoff, sliding-window token bucket rate limiting, and storm quorum damping.
- Consistent Hashing Ring Topology & Virtual Node Distribution Fabric: Virtual node topology, Murmur3/FNV-1a distribution, clockwise binary search routing, multi-replica fault tolerance, and dynamic partition rebalancing.
- Distributed Event Mesh Telemetry Aggregation & Adaptive Backpressure Throttling: Zero-allocation bounded sliding window telemetry aggregation, credit-based backpressure protocol, and AIMD congestion control across subscriber worker pools.
- Event Mesh Flow Control, Token Bucket Rate Limiting, and Starvation Prevention: Thread-safe token bucket rate limiting with burst allowances, deficit round-robin multi-tenant fair queueing, and starvation prevention across event mesh subscribers.
5. Swarms, Orchestration & Extensibility
Documents governing multi-agent coordination, bounded domain packages, and extensible modules.
- Pack Composition & Extensibility Architecture: Architectural distinction between Go Code Packs (
packs/<domain>) and Runtime Swarm Orchestration Packs (swarm.yaml), and composition rules. - Kernel-to-Vendor Instruction Projection: Automated projection of kernel directives, behavioral policies, and context into vendor-specific agent instructions (
AGENTS.md,.cursorrules,.windsurfrules). - Composite Execution Organizer Verification: End-to-end trace pipelines, deterministic goal hierarchy composition, and verification gates.
- Adaptive Task Supervision Specification: Multi-agent supervisor coordination, heartbeat monitoring, and automated unsticking protocols.
- Adaptive Agent Disambiguation: Persona resolution, skill linkage, and intent disambiguation for agent execution seats.
- Orchestration Runtime Taxonomy: Classification of swarm coordinators, seat workers, and task queues.
- Package Consolidation Governance: Package boundary hygiene, circular import prevention, and internal vs public API separation.
- SpecBuilder CodeGen & Enum Consolidation: SpecBuilder code generation, AST pruning, and domain enum aggregation.
- Synthetic Constant Eradication Governance: Elimination of stringly-typed magic constants in favor of canonical spec-derived constants.
- Vendor-Agnostic Anti-Idle Continuation Hook Architecture: Standardized lifecycle continuation hook adapters, non-interrupting steering feeds, and fail-closed anti-idleness in autonomous CAP loops.
6. Security, Sovereign Execution & Cryptography
Documents governing cryptographic provenance, keys, sovereign local execution, and execution isolation.
- Sovereign Air-Gapped AI Engineering: Offline execution with local LLMs (Ollama / Apple Silicon), local CAS persistence, and deterministic AST verification.
- Keystore Security & Fallback Specification: Ed25519 signing keys, fail-closed key discovery, and environment variable resolution.
- Tray Command Cryptographic Security: Authenticated RPC protocol between background daemons and desktop tray applications.