Architecture Links

A comprehensive guide to all architecture documentation in C-Kernel-Engine.

Runbooks

v8 Numerical Contracts

How weights, circuits, kernel-map capabilities, complete reduction semantics, deterministic lowering, and parity gates prevent ad hoc runtime dispatch.

circuitskernel mapsreduction contracts

Open Numerical Contracts

Kernel Maps and Provider Selection

How the v8 resolver picks a provider mechanically: the three-level separation, the map field reference, worked memcpy/GEMM/KV-cache examples, the fail-closed ranking rules, and the migration scoreboard.

kernel maps provider selection equivalence groups fail-closed

Open Kernel Maps

X-Ray: Evidence and Divergence Attribution

How CKE proves numerical correctness: the join-don't-instrument pipeline, checkpoint records, three-state verdicts and the honest scorecard, capture neutrality gates, failure classes, fix ownership, and the IR visualizer X-Ray tab.

x-ray parity capture neutrality fix ownership

Open X-Ray

The CKE Constraint Model

Theory of Constraints as runtime math: per-region clocks (compute, cache, DRAM, network, storage), region time as max-plus-unhidden-sync, the exposed-transfer equation, the critical-path shard scheduler, and the prediction-error control loop that ties Scaling, CKU, Memory Tetris and Zip Fusion into one theory.

theory of constraints critical path control loop

Open the Constraint Model

Memory Tetris

Research design for DRAM as a software-managed tensor cache over NVMe: arena slots, prefetch overlap, safety contracts, and X-Ray evidence. Proposed, not implemented.

NVMe tiering prefetch research design

Open Memory Tetris

Distributed CPU: Zip Fusion

Research design for whole-graph distributed CPU scheduling: fused 1-D lanes that unzip to 2-D head-by-context attention, sync boundaries per layer as the metric, and a measurement-first plan. Proposed, not implemented.

distributed CPU zip fusion research design

Open Zip Fusion

v8 Runbook

The scoped operator runbook for the validated v8 lanes. v8 now supports vision (Qwen3-VL) and audio (Whisper Tiny) alongside text-family bring-up; the canonical commands for each lane live on the runbook page.

cks-v8-run ck_run_v8.py Qwen3-VL run_whisper_v8.py

Open v8 Runbook

v8 Vision Encoder Architecture

Design page for how the v8 vision encoder is derived from GGUF + template + lowering, then stitched into the decoder bridge.

qwen3_vl_vision.json build_ir_v8.py encoder → bridge → decoder

Open Vision Encoder Page

Whisper Tiny End-to-End

Audio inference through the same circuit and kernel-contract path: PCM16 WAV to log-Mel, generated FP32 encoder and decoder, nightly audio gates, and the opt-in E2E artifact test.

audio_transformer_*.json run_whisper_v8.py WAV → log-Mel → encoder → decoder

Open Whisper Tiny Page

v7 Inference + Training Runbook

Copy/paste workflow for HF GGUF inference plus true_bpe training and train->infer handoff.

ck_run_v7.py run train_data_pipeline_v7.py ck_chat.py

Open v7 Runbook

v7 Python Authoring Guide

Step-by-step notebook launch order, Python authoring syntax, and the exact handoff boundary from notebooks or ck.nn into the existing v7 scripts.

TrainingProject ck.v7.compile(...) notebooks 01 → 05

Open Python Authoring Guide

v7 Profiling Runbook

Repeatable performance workflow for v7 training kernels with perf, VTune, flamegraphs, and Advisor.

perf vtune advisor

Open v7 Profiling

Kernel Tuning Methodology

CPU-node tuning loop for v8/v7 kernels: practical coherence, fixed-token throughput, CK profile CSV, VTune, Advisor roofline, microkernel labs, and PR logs.

VTune Advisor roofline CK_PROFILE

Open Methodology

Stitched Divergence Harness

Backend parity method for finding the first CK-vs-reference tensor boundary across llama.cpp/mtmd GGUF lanes and future PyTorch adapters.

CKDMP llama.cpp/mtmd first divergence

Open Harness Guide

v7 SVG Dataset Runbook

Operator workflow to generate Stage A pretraining and Stage B midtraining SVG corpora from docs/site/assets/*.svg, then hand off to v7 training.

build_svg_corpus_from_assets_v7.py prepare_ascii_dataset_v7.py curriculum-stage stage_a|stage_b

Open SVG Dataset Runbook

Core

System Overview IR, Codegen, Kernels
v8 Numerical Contracts Circuits, kernel capabilities, deterministic reduction resolution, and parity gates
Kernel Maps and Provider Selection 297 machine-checked maps, the fail-closed resolver, and the migration scoreboard
v8 Kernel Architecture The registry by operation family: selection rules, equivalence groups, and the math behind each kernel class
Architecture Variants What Laguna, Cohere2, Instella, and Nemotron-H each forced the kernel registry to grow
MoE Expert Kernels Grouped/bucketed expert prefill, mixed-quant compact experts, parallel throughput kernels
Cohere Kernel Story Command R provider reuse, North MoE, Compass BF16 vision, Transcribe audio foundation
IR Pipeline v6.6 Templates → IR1 → IR2 → Lowering
v7 Backprop IR Pipeline Init → IR1 → IR2 → Layout → Codegen + canary diagnostics
v7 Cross-Entropy Parity p - one_hot derivation, PyTorch semantics, long-horizon drift fixes
v7 Grad-Accum Windows Micro-batch vs effective batch, N vs K, CPU batch simulation
v7 Train Data Pipeline One-command dataset -> tokenizer -> train orchestration
v7 Runtime Stitch Graph Function-level forward/backward/accum/optimizer stitching view
v8 Runbook Current operator path for validated v8 text, vision, and Whisper Tiny audio inference
v8 Vision Encoder Architecture How GGUF intake, template lowering, memory planning, and bridge stitching power the working vision path
v8 MLA / Kimi Decode Cache Kimi/DeepSeek-style MLA template contract, explicit cache store/read lowering, and reference kernels
Whisper Tiny End-to-End Generated FP32 audio encoder/decoder circuits from PCM16 WAV, with the pipeline infographic, nightly gates, and current limitations
v7 Inference + Training Runbook Copy/paste commands for HF GGUF inference + true_bpe training
v7 Python Authoring Guide Notebook lane, TrainingProject, and ck.v7.compile(...) in one place
v7 SVG Dataset Runbook Dataset generation for Stage A pretrain and Stage B midtrain
Model + Kernel Matrix Qwen2/Qwen3/Gemma + kernel coverage
Tokenizer BPE, WordPiece, Trie
Kernel Reference Forward/backward ops
Gated DeltaNet Deep Dive Qwen3.5/qwen3next recurrent attention state update and kernel parity
Audio Kernels Deep Dive WAV decode, resample, STFT, log-Mel, Conv1D stem, token transpose — math and parity oracles per kernel
Code Generation IR to C compilation
Iteration Philosophy Why v1→v6 matters
IR v2 Format Case study: symbolic dimensions
Deep Dive Concepts RoPE, Flash Attention, GQA

Quantization

Quant Fundamentals Block formats, grouping
Bit Manipulation Visuals Q5_0, Q4_K, INT8 with spaced repetition
Quant Format Reference Byte-level visualization
GGUF to Bump Weight conversion
GGUF Parsing Byte-level guide

Optimization

GEMM Memory Layout NN/NT layouts, offsets
GEMM Optimization AVX, MKL, blocking
v7 Train Layout + Dispatch IR3 memory + parallel execution plan
Threadpool GEMM Playbook Split M/N/K policy for training
Kernel Tuning Methodology VTune, Advisor, roofline, CK profile, parity, and benchmark log discipline
SIMD Architecture AVX-512, VNNI, AMX
Flash Attention Analysis Why llama.cpp is faster

Infrastructure

Memory Safety Bump allocator, canaries
Deterministic Memory RDMA, interpretability
The CKE Constraint Model Umbrella math tying Scaling, CKU, Memory Tetris and Zip into one control loop
Memory Tetris Research design: DRAM as a tensor cache over NVMe (not implemented)
Distributed CPU: Zip Fusion Research design: whole-graph scheduling across CPU nodes (not implemented)
Profiling Guide Valgrind, perf, flamegraphs
Kernel Tuning Methodology CPU-node roofline workflow for v8/v7 kernel performance work
v8 Runbook Validated text, vision, and Whisper Tiny audio operator workflows
v8 Vision Encoder Architecture Bridge and encoder design notes for the current multimodal inference lane
Whisper Tiny End-to-End Generated audio encoder/decoder circuits, pipeline infographic, nightly gates
v7 Profiling Runbook VTune + Advisor + perf/flamegraph on train kernels
v7 Inference + Training Runbook Operational workflow from dataset to chat output
v7 Python Authoring Guide Notebook-driven and module-driven authoring entrypoints for the same v7 runtime
Testing Numerical parity verification
X-Ray: Evidence and Divergence Attribution Schema-validated parity evidence, capture neutrality, fix ownership
Stitched Divergence Harness First failing tensor boundary across CK and reference backends

Temp / Work in Progress

Draft Documentation
These pages are work-in-progress and may be moved or updated.

Quantization Math Deep Dive

Explains Q5_0/Q8_0 block formats, dequantization math, and AVX-512 vectorization strategy.

GEMM Memory Layout

Covers quantized block storage, cache blocking strategies, and KV cache layouts.

By Task

Task	Documentation
Understanding the system	System Overview, Concepts, v7 Backprop IR, v7 CE Parity, v7 Grad-Accum Windows, v7 Runbook, v7 Python Authoring Guide
Implementing new kernels	Kernel Reference, Gated DeltaNet Deep Dive, Codegen
Quantization work	Quant Fundamentals, Bit Visuals, GGUF Parsing
Performance optimization	Kernel Tuning Methodology, GEMM Layout, v7 Train Layout+Dispatch, Threadpool Playbook, SIMD
Debugging & profiling	Kernel Tuning Methodology, Profiling, v7 Profiling Runbook, Testing, Stitched Divergence Harness, v7 CE Parity Deep Dive, v7 Runtime Stitch Graph, v7 Runbook, v7 Python Authoring Guide
Operator train + compute workflow	v7 SVG Dataset Runbook, v7 Inference + Training Runbook, v7 Python Authoring Guide, v7 Profiling Runbook