This directory holds the Architecture Decision Records (ADRs) for Zerfoo. Each ADR captures a single significant decision -- its context, the decision itself, and the consequences -- so the reasoning behind the framework's shape stays discoverable long after the change lands.
- Accepted -- decision is in force.
- Proposed -- under consideration, not yet adopted.
- Superseded -- replaced by a later ADR (noted in the title cell when the file states it).
- Rejected -- considered and declined.
- Copy the next number in sequence (the last entry below is ADR 093).
- Name the file
NNN-short-kebab-title.md. - Include
# ADR-NNN: Title, a## Status,## Date,## Context,## Decision, and## Consequencessection. - Add a row to the table below (kept sorted by number).
| ADR | Title | Status | Date |
|---|---|---|---|
| 001 | Enterprise Production Readiness | Accepted | 2026-03-01 |
| 002 | Distributed Training Protocol | Accepted | 2026-03-01 |
| 003 | Open Weights Model Import | Accepted | 2026-03-02 |
| 004 | Embeddable Inference Library | Accepted | 2026-03-02 |
| 005 | Multi-Architecture Support | Accepted | 2026-03-02 |
| 006 | GPU Engine Architecture | Accepted | 2026-03-01 |
| 007 | Multi-GPU Architecture | Accepted | 2026-03-03 |
| 008 | cuDNN Integration | Accepted | 2026-03-03 |
| 009 | TensorRT Integration | Accepted | 2026-03-03 |
| 010 | CUTLASS Flash Attention | Accepted | 2026-03-03 |
| 011 | GPU Runtime Abstraction Layer (GRAL) | Accepted | 2026-03-03 |
| 012 | AMD ROCm Backend | Accepted | 2026-03-03 |
| 013 | OpenCL Backend | Accepted | 2026-03-03 |
| 014 | cuDNN Backward Pass | Accepted | 2026-03-03 |
| 015 | CUTLASS Quantized GEMM Kernels | Accepted | 2026-03-03 |
| 016 | TensorRT Dynamic Shape Support | Accepted | 2026-03-03 |
| 017 | DGX Spark Hardware Validation | Accepted | 2026-03-03 |
| 018 | Model Parity Testing on DGX Spark | Accepted | 2026-03-04 |
| 019 | Phase 22 -- BF16 GEMM, Unified Memory, SigLIP Fix | Accepted | 2026-03-05 |
| 020 | Q4 Quantized Dot Product | Accepted | 2026-03-06 |
| 021 | Graph Compilation and Persistent Worker Pool | Accepted | 2026-03-06 |
| 022 | GPU-First Inference Pipeline | Accepted | 2026-03-06 |
| 023 | GPU Scalar Ops and D2H Elimination Strategy | Accepted | 2026-03-06 |
| 024 | CUDA Graph Capture and Fused Kernels for Inference Acceleration | Accepted | 2026-03-06 |
| 025 | Replace CGo with purego for CUDA Bindings | Accepted | 2026-03-06 |
| 026 | Megakernel Code Generation for Single-Launch Decode | Accepted (revised) | 2026-03-06 |
| 027 | Enforce Layer Composition Before Megakernel | Accepted | 2026-03-07 |
| 028 | Tracing Compiler for Automatic Primitive Op Decomposition | Accepted | 2026-03-07 |
| 029 | NEON SIMD CPU Acceleration for Inference Parity with llama.cpp | Accepted | 2026-03-07 |
| 030 | Ollama Performance Parity Strategy | Accepted | 2026-03-11 |
| 031 | OpenAI-Compatible Inference Server Lives in Zerfoo | Accepted | 2026-03-12 |
| 032 | GPU-Resident Position Counter for CUDA Graph Capture | Accepted | 2026-03-14 |
| 033 | How Zerfoo Surpassed Ollama — 241 tok/s on DGX Spark GB10 | Accepted | 2026-03-14 |
| 034 | GQA-Aware Flash Attention Decode Kernel | Accepted | 2026-03-14 |
| 035 | Gemma 3 Architecture Parameterization | Accepted | 2026-03-11 |
| 036 | Extract ztensor and ztoken as Independent Repositories | Accepted | 2026-03-15 |
| 037 | GGUF as Sole Model Format, Drop ZMF for Model Storage | Accepted | 2026-03-15 |
| 038 | Structured Output via Grammar-Guided Decoding | Accepted | 2026-03-15 |
| 039 | HuggingFace Model Download via zerfoo pull | Accepted | 2026-03-15 |
| 040 | Native GGUF GEMV Kernels Instead of Re-Quantization | Accepted | 2026-03-17 |
| 041 | FP16 Weight Dequantization Instead of Native GEMV Kernels | Accepted | 2026-03-17 |
| 042 | dp4a INT8 Q4_K GEMV with FP32 FMA Fallback | Accepted | 2026-03-17 |
| 043 | Arena Free-List with Tensor Lifetime Analysis | Accepted | 2026-03-17 |
| 044 | PagedAttention KV Block Manager | Accepted | 2026-03-17 |
| 045 | Speculative Decoding Implementation Strategy | Accepted | 2026-03-17 |
| 046 | FP8 and NVFP4 Quantization Roadmap | Accepted | 2026-03-17 |
| 047 | Disaggregated Prefill/Decode Serving | Accepted | 2026-03-17 |
| 048 | Mamba/SSM Architecture Support | Accepted | 2026-03-17 |
| 049 | LoRA/QLoRA Fine-Tuning Infrastructure | Accepted | 2026-03-17 |
| 050 | Distributed Training FSDP-Equivalent | Accepted | 2026-03-17 |
| 051 | Wolf Time-Series ML Platform | Accepted | 2026-03-17 |
| 052 | Online Learning Safety Framework | Accepted | 2026-03-17 |
| 053 | Multi-Modal Inference Pipeline | Accepted | 2026-03-17 |
| 054 | Agentic Tool-Use and Loop Supervisor | Accepted | 2026-03-17 |
| 055 | Neural Architecture Search for Wolf Trading Models | Accepted | 2026-03-17 |
| 056 | Zerfoo Cloud Product Architecture | Proposed | 2026-03-17 |
| 057 | Open-Core Licensing Strategy | Accepted | 2026-03-18 |
| 058 | API Stability v1.0 Contract | Accepted | 2026-03-18 |
| 059 | Zerfoo Runtime -- Edge Inference Architecture | Accepted | 2026-03-18 |
| 060 | Zerfoo Cloud Platform Architecture | Accepted | 2026-03-18 |
| 061 | Shared GGUF Writer in ztensor | Accepted | 2026-03-18 |
| 062 | Tabular Model Package | Accepted | 2026-03-18 |
| 063 | Financial Sentiment Analysis Architecture | Accepted | 2026-03-20 |
| 064 | Use Hugo for Documentation Site | Accepted | 2026-03-21 |
| 065 | Security Middleware Integration | Accepted | 2026-03-21 |
| 066 | Replace finite-difference gradients with analytical backprop in timeseries CPU training | Accepted | 2026-03-24 |
| 067 | MSA-Inspired Sparse Attention for Scalable Memory | Accepted | 2026-03-27 |
| 068 | Research-Driven Inference Optimization Priorities | Accepted | 2026-03-27 |
| 069 | TransMLA -- Retrofit MLA onto MHA/GQA Models | Accepted | 2026-03-27 |
| 070 | Make RoPE Optional in GQA for Non-Rotary Architectures | Accepted | 2026-03-28 |
| 071 | Sigmoid MoE Gating with Routing Bias | Accepted | 2026-03-28 |
| 072 | Kimi Linear Attention Layer | Accepted | 2026-03-28 |
| 073 | mmap Default Loading and Split-GGUF Support | Accepted | 2026-03-28 |
| 074 | Satellite Libraries v1 Release Policy | Accepted | 2026-03-29 |
| 075 | Batched Training with Kernel Fusion for Time Series Backends | Accepted | 2026-03-29 |
| 076 | Native Go Foundation Model Inference via GGUF | Accepted | 2026-03-29 |
| 077 | CUDA Graph Capture for Time Series Training | Accepted | 2026-03-30 |
| 078 | Remove gonum.org/v1/gonum Dependency | Accepted | 2026-04-01 |
| 079 | PJRT Multi-Accelerator Backend via purego | Accepted | 2026-04-01 |
| 080 | KV Cache as Explicit I/O for PJRT Execution Path | Accepted | 2026-04-01 |
| 081 | StableHLO Text Generation over HLO Protobuf | Accepted | 2026-04-01 |
| 082 | Composition Remediation Strategy | Accepted | 2026-04-02 |
| 083 | Spark as the bench runner for DGX GPU workloads | Accepted | 2026-04-07 |
| 084 | Extract crossasset package from zerfoo to wolf | Accepted | 2026-04-12 |
| 085 | Gemma 4 Architecture Support | Accepted | 2026-04-13 |
| 086 | Adopt the Canonical Shared-PLE-Plus-Per-Layer-Proj Layout for Gemma 4 Edge | Accepted | 2026-04-13 |
| 087 | External K/V Input Path for GroupedQueryAttention | Accepted | 2026-04-13 |
| 088 | CUDA Graph Capture Compatibility for Gemma 4 Edge PLE Combiner | Accepted | 2026-04-15 |
| 089 | CUDA Graph Capture Compatibility for LMHead | Proposed (awaiting ztensor ship) | 2026-04-16 |
| 090 | OSS scope of cloud/, marketplace/, and compliance/ in zerfoo | Accepted | 2026-04-27 |
| 091 | Per-op verification harnesses -- gradcheck, engine parity under arena stress, and PyTorch as oracle | Accepted | 2026-06-10 |
| 092 | LTX-2 diffusion audio/video inference -- DiT-first, via general primitives | Proposed | 2026-06-16 |
| 093 | H2 2026 Product Strategy -- Trust, then Traction | Accepted | 2026-07-02 |