# ZINC Zig API

Primary generated reference for the ZINC Zig runtime and supporting Vulkan compute modules.

Primary docs: https://zolotukhin.ai/zinc/docs/zig-api
JSON export: https://zolotukhin.ai/zinc/docs/zig-api.json
Text export: https://zolotukhin.ai/zinc/docs/zig-api.txt
LLMs index: https://zolotukhin.ai/llms.txt
Last updated: 2026-07-19
Counts: 16 sections, 93 modules, 119020 Zig code lines, 654 exports, 476 methods.

Guidance: Use the generated Zig API as the canonical internal runtime reference. Use the Serving HTTP API doc only for the client-facing network protocol.

## CLI & Entrypoints

Startup, argument parsing, and the top-level process path that wires model loading, tokenization, and generation together.
URL: https://zolotukhin.ai/zinc/docs/zig-api#cli-entrypoints

### Module: Build Info
URL: https://zolotukhin.ai/zinc/docs/zig-api/build-info/
Source: src/build_info.zig
Code lines: 30
Summary: Build metadata exported by `build.zig` for CLI version reporting.
Overview: The values in this module are generated at compile time from build options such as `-Dversion` and `-Dcommit`, then printed by `zinc --version`.

- version [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/build-info/#version
  Signature: pub const version = build_options.version
  Summary: Semantic version string for this build (from `-Dversion`, e.g.
  Description: `0.3.1`).

- commit [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/build-info/#commit
  Signature: pub const commit = build_options.commit
  Summary: Short git commit hash this binary was built from (from `-Dcommit`).

- target [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/build-info/#target
  Signature: pub const target = build_options.target
  Summary: Compilation target triple this binary was built for (from `-Dtarget`).

- optimize [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/build-info/#optimize
  Signature: pub const optimize = build_options.optimize
  Summary: Active optimize mode, e.g.
  Description: `ReleaseFast` or `Debug` (from `-Doptimize`).

- backend [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/build-info/#backend
  Signature: pub const backend = build_options.backend
  Summary: GPU backend(s) compiled into this binary, e.g.
  Description: `vulkan` or `metal`.

- writeVersion [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/build-info/#write-version
  Signature: pub fn writeVersion(writer: anytype) !void
  Summary: Write the full `zinc --version` report to `writer`.
  Description: Emits the version, commit, target, optimize mode, and compiled-in backends, each on its own line.
  Param writer: Destination writer that receives the formatted metadata block.
  Returns: Propagates only the writer's own error if printing fails.

### Module: CLI
URL: https://zolotukhin.ai/zinc/docs/zig-api/main/
Source: src/main.zig
Code lines: 2747
Summary: CLI entrypoints for configuring ZINC and starting local inference.
Overview: This module wires together GPU initialization, model loading, tokenization, and the single-process decode loop used for prompt-mode execution.

- is_debug_mode [variable]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/main/#is-debug-mode
  Signature: pub var is_debug_mode: bool = false
  Summary: Global flag enabling verbose debug log output when `--debug` is passed or the `ZINC_DEBUG` env var is set.

- std_options [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/main/#std-options
  Signature: pub const std_options = std.Options{
  Summary: Zig standard library options — sets log level to debug and wires the custom log function.

- myLogFn [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/main/#my-log-fn
  Signature: pub fn myLogFn( comptime level: std.log.Level, comptime scope: @TypeOf(.enum_literal), comptime format: []const u8, args: anytype, ) void
  Summary: Custom log handler that filters debug messages unless `is_debug_mode` is set.
  Param level: Severity level; debug messages are suppressed when `is_debug_mode` is false.
  Param scope: Call-site scope tag; displayed as `(<scope>):` or `: ` for the default scope.
  Param format: Comptime format string passed through to `std.debug.print`.
  Param args: Runtime arguments matched to `format`.

- Config [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/main/#config
  Signature: pub const Config = struct
  Summary: Runtime configuration built from CLI flags and default values.

- Command [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/main/#command
  Signature: pub const Command = enum
  Summary: Top-level CLI subcommands parsed from argv.

- parseArgs [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/main/#parse-args
  Signature: pub fn parseArgs(args: []const [:0]const u8) !Config
  Summary: Parse the process argument vector into a validated runtime configuration.
  Param args: Raw argv slice, including argv[0].
  Returns: A populated Config value or a validation error describing the first invalid flag.

- main [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/main/#main
  Signature: pub fn main() !void
  Summary: Parse arguments, dispatch model-management commands, run diagnostics, or start inference.
  Description: In prompt mode the engine runs up to `max_tokens` forward passes and prints the decoded output. In server mode an HTTP listener is started and requests are handled until SIGINT/SIGTERM.
  Note: Fatal startup errors are logged and the process exits rather than returning an error.

### Module: Zig-struct-analyzer
URL: https://zolotukhin.ai/zinc/docs/zig-api/zig-struct-analyzer/
Source: src/zig-struct-analyzer.zig
Code lines: 4
Summary: Generated struct-layout probe used by the site Zig API docs.
Overview: The docs build emits a temporary Zig file that imports selected public structs and prints their size, alignment, and field offsets; this runner simply dispatches to that generated probe.

- main [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/zig-struct-analyzer/#main
  Signature: pub fn main() !void
  Summary: Run the generated struct-layout probe used by the site Zig API docs build.

### Module: CLI
URL: https://zolotukhin.ai/zinc/docs/zig-api/main/
Source: src/zinc_rt/main.zig
Code lines: 568
Summary: ZINC_RT backend entrypoint.
Overview: The M0 binary is intentionally small: it brings up tier selection and the T-CPU packet runner without linking the Vulkan backend. Pass `--prompt` to drive the host-assisted forward path, or `--probe-tier` to report tier admission status without running a model. The tenant-aware batch planner lives in `zinc_rt.batching`; the CLI does not yet expose the HTTP server or end-to-end batched inference executor.

- std_options [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/main/#std-options
  Signature: pub const std_options = std.Options{
  Summary: Zig standard library log configuration for the zinc_rt binary.
  Description: Lowering this to `.debug` keeps the M0 trace prints visible without an extra build flag; the engine itself respects `ZINC_RT_LOG_LEVEL`.

- main [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/main/#main
  Signature: pub fn main() !void
  Summary: Process entrypoint for the `zinc` binary built with `-Dbackend=zinc_rt`.
  Description: Parses CLI flags, selects the runtime tier from `ZINC_RT_TIER`, and dispatches to the help, probe, prompt, or T-CPU smoke path. with status 1 on argument or tier-parse failures.
  Returns: Propagates any allocation, argument, or runtime error; exits

## Model Format & Loading

GGUF parsing, metadata normalization, and the runtime structures that move weights from disk into GPU-resident buffers.
URL: https://zolotukhin.ai/zinc/docs/zig-api#model-format-loading

### Module: Config
URL: https://zolotukhin.ai/zinc/docs/zig-api/config/
Source: src/model/config.zig
Code lines: 94
Summary: Platform-independent model types shared by Vulkan and Metal backends.
Overview: The actual extraction logic lives in loader.zig (Vulkan) and loader_metal.zig (Metal). Both share this config type for GGUF parsing, but keep separate loaders because loader.zig has Vulkan imports at the top level.

- Architecture [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/config/#architecture
  Signature: pub const Architecture = enum
  Summary: Supported model families inferred from GGUF architecture metadata.
  Description: Multiple GGUF architecture strings may collapse to a single variant — for example `"llama"` maps to `.mistral` and `"qwen3"` maps to `.qwen2` because their forward-pass implementations are identical. `.unknown` is returned for any unrecognised string.

- ModelConfig [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/config/#model-config
  Signature: pub const ModelConfig = struct
  Summary: Normalized model dimensions and routing metadata extracted from GGUF fields.
  Description: SSM-specific fields (`ssm_d_*`, `ssm_n_group`, `full_attn_interval`) default to zero and are only meaningful for Mamba/Jamba/Qwen3.5 hybrid architectures. RoPE section fields (`rope_sections`, `rope_attn_factor`, `rope_scaling_factor`, `rope_original_context`) are used only by the `qwen35` IMRoPE scheme.

- parseArchitecture [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/config/#parse-architecture
  Signature: pub fn parseArchitecture(arch_str: []const u8) Architecture
  Summary: Map a GGUF `general.architecture` string to an `Architecture` variant.
  Description: The mapping is many-to-one: architecturally equivalent families share a variant (e.g. `"llama"` → `.mistral`, `"qwen3"` → `.qwen2`), so callers must not assume the variant name matches the original GGUF string.
  Param arch_str: The raw architecture string from GGUF metadata, e.g. `"qwen2"`.
  Returns: The matching `Architecture` variant, or `.unknown` if unrecognised.

### Module: GGUF
URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/
Source: src/model/gguf.zig
Code lines: 451
Summary: Parse GGUF container files and expose the metadata needed by the loader.
Overview: The helpers in this module decode GGUF headers, metadata values, tensor offsets, and GGML quantization information without copying the whole file.

- GGUF_MAGIC [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#gguf-magic
  Signature: pub const GGUF_MAGIC: u32 = 0x46554747
  Summary: Little-endian magic value expected at the start of every GGUF file.

- GGUFVersion [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#ggufversion
  Signature: pub const GGUFVersion = enum(u32)
  Summary: GGUF container versions recognized by the parser.

- GGUFType [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#gguftype
  Signature: pub const GGUFType = enum(u32)
  Summary: Primitive metadata value tags defined by the GGUF format.

- GGMLType [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#ggmltype
  Signature: pub const GGMLType = enum(u32)
  Summary: GGML tensor storage and quantization formats referenced by GGUF tensors.
  - GGMLType.blockSize [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#ggmltype-block-size
    Signature: pub fn blockSize(self: GGMLType) u32
    Summary: Return the number of tensor elements encoded by one storage block.
    Param self: GGML tensor format to inspect.
    Returns: The number of logical elements represented by one block of this format.
    Note: Quantized formats pack many elements into one block, while plain scalar types return `1`.
  - GGMLType.bytesPerBlock [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#ggmltype-bytes-per-block
    Signature: pub fn bytesPerBlock(self: GGMLType) u32
    Summary: Return the serialized byte width of one storage block.
    Param self: GGML tensor format to inspect.
    Returns: The number of on-disk bytes consumed by one block of this format.
    Note: Use this together with `blockSize()` to convert element counts into tensor byte ranges.

- MetadataValue [union]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#metadata-value
  Signature: pub const MetadataValue = union(enum)
  Summary: Typed representation of a GGUF metadata value.
  - MetadataValue.asString [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#metadata-value-as-string
    Signature: pub fn asString(self: MetadataValue) ?[]const u8
    Summary: Interpret the metadata value as a string slice when the stored type is `.string`.
    Returns: The string contents, or `null` when the value is not a string.
  - MetadataValue.asU32 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#metadata-value-as-u32
    Signature: pub fn asU32(self: MetadataValue) ?u32
    Summary: Interpret the metadata value as an unsigned 32-bit integer when it fits.
    Returns: A normalized `u32` or `null` when the stored value cannot be represented as one.
  - MetadataValue.asU64 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#metadata-value-as-u64
    Signature: pub fn asU64(self: MetadataValue) ?u64
    Summary: Interpret the metadata value as an unsigned 64-bit integer when it fits.
    Returns: A normalized `u64` or `null` when the stored value cannot be represented as one.
  - MetadataValue.asF32 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#metadata-value-as-f32
    Signature: pub fn asF32(self: MetadataValue) ?f32
    Summary: Interpret the metadata value as a 32-bit floating-point number when possible.
    Returns: An `f32` value or `null` when the stored value is not a floating-point type.
  - MetadataValue.asBool [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#metadata-value-as-bool
    Signature: pub fn asBool(self: MetadataValue) ?bool
    Summary: Interpret the metadata value as a boolean when possible.
    Returns: A normalized `bool` or `null` when the stored value is not boolean-like.

- TensorInfo [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#tensor-info
  Signature: pub const TensorInfo = struct
  Summary: Tensor descriptor read from the GGUF header for a single named weight tensor.
  - TensorInfo.numElements [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#tensor-info-num-elements
    Signature: pub fn numElements(self: *const TensorInfo) u64
    Summary: Multiply the active tensor dimensions to get the logical element count.
    Param self: Tensor descriptor to inspect.
    Returns: The total number of logical elements across the first `n_dims` entries in `dims`.
  - TensorInfo.sizeBytes [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#tensor-info-size-bytes
    Signature: pub fn sizeBytes(self: *const TensorInfo) u64
    Summary: Compute the serialized tensor byte size for the descriptor's GGML storage format.
    Param self: Tensor descriptor to inspect.
    Returns: The number of bytes occupied by the tensor payload, rounded up to whole quantization blocks.
    Note: Quantized tensors round element counts up to a full block before multiplying by bytes-per-block.

- GGUFFile [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#gguffile
  Signature: pub const GGUFFile = struct
  Summary: Fully decoded GGUF file: header fields, key-value metadata, and tensor descriptor table.
  - GGUFFile.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#gguffile-deinit
    Signature: pub fn deinit(self: *GGUFFile) void
    Summary: Release metadata keys, metadata payloads, and tensor names owned by the parsed file.
    Param self: Parsed GGUF file to tear down in place.
  - GGUFFile.getString [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#gguffile-get-string
    Signature: pub fn getString(self: *const GGUFFile, key: []const u8) ?[]const u8
    Summary: Look up a metadata string value by key.
    Param self: Parsed GGUF file.
    Param key: Metadata key to search for.
    Returns: The stored string value when present and typed as `.string`.
  - GGUFFile.getU32 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#gguffile-get-u32
    Signature: pub fn getU32(self: *const GGUFFile, key: []const u8) ?u32
    Summary: Look up a metadata value as `u32` when it can be normalized to that type.
    Param self: Parsed GGUF file.
    Param key: Metadata key to search for.
    Returns: The normalized integer value when present.
  - GGUFFile.getF32 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#gguffile-get-f32
    Signature: pub fn getF32(self: *const GGUFFile, key: []const u8) ?f32
    Summary: Look up a metadata value as `f32` when it can be normalized to that type.
    Param self: Parsed GGUF file.
    Param key: Metadata key to search for.
    Returns: The normalized floating-point value when present.
  - GGUFFile.getBool [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#gguffile-get-bool
    Signature: pub fn getBool(self: *const GGUFFile, key: []const u8) ?bool
    Summary: Look up a metadata value as `bool` when it can be normalized to that type.
    Param self: Parsed GGUF file.
    Param key: Metadata key to search for.
    Returns: The normalized boolean value when present.
  - GGUFFile.findTensor [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#gguffile-find-tensor
    Signature: pub fn findTensor(self: *const GGUFFile, name: []const u8) ?*const TensorInfo
    Summary: Find a tensor descriptor by name.
    Param self: Parsed GGUF file.
    Param name: Tensor name to look up.
    Returns: A pointer to the tensor descriptor when the tensor exists.

- ParseOptions [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#parse-options
  Signature: pub const ParseOptions = struct
  Summary: Optional flags that control GGUF parsing behavior.

- parse [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#parse
  Signature: pub fn parse(data: []const u8, allocator: std.mem.Allocator) !GGUFFile
  Summary: Parse a GGUF file from a byte slice.
  Param data: Raw GGUF bytes, typically from a memory-mapped file.
  Param allocator: Allocator used for metadata strings, arrays, and tensor descriptors.
  Returns: A `GGUFFile` with all data heap-allocated; call `deinit` to free all owned memory.

- parseWithOptions [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/gguf/#parse-with-options
  Signature: pub fn parseWithOptions(data: []const u8, allocator: std.mem.Allocator, options: ParseOptions) !GGUFFile
  Summary: Parse a GGUF file from a byte slice with optional logging control.
  Param data: Raw GGUF bytes, typically from a memory-mapped file.
  Param allocator: Allocator used for metadata keys, string values, array payloads, and tensor name copies.
  Param options: Flags controlling parse-time side effects such as summary logging.
  Returns: A `GGUFFile` whose string data is heap-allocated; call `deinit` to free all owned memory.
  Note: Returns `error.InvalidMagic` when the four-byte magic is wrong, or `error.UnknownMetadataType` for unrecognized type tags.

### Module: Loader Cuda
URL: https://zolotukhin.ai/zinc/docs/zig-api/loader-cuda/
Source: src/model/loader_cuda.zig
Code lines: 556
Summary: CUDA-specific model loading — mmap the GGUF, upload every tensor to the NVIDIA device, and expose them to the CUDA forward pass.
Overview: Unlike the Metal loader (Apple unified memory, zero-copy newBufferWithBytesNoCopy), CUDA device memory is NOT CPU-visible, so each tensor is copied host->device once at load time via `cuda_buffer.uploadMmap`. The file mapping is kept alive after upload because the embedding lookup (`dequantEmbeddingRow`) dequantizes a single `token_embd.weight` row on the CPU directly out of the mapping.
Overview: GGUF parsing and config extraction are backend-agnostic; the config extractor below is copied verbatim from loader_metal.zig (pure metadata reads, no backend dependency). `dequantRow`/`getScaleMinK4` are copied from compute/forward_metal.zig to avoid importing the Metal forward pass (which would drag in Metal-only dependencies).

- LoadedTensor [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loader-cuda/#loaded-tensor
  Signature: pub const LoadedTensor = struct
  Summary: A GGUF tensor descriptor paired with the device buffer holding its weights.
  Description: `info` carries the on-disk shape/quant/offset metadata; `gpu_buffer` is the device-local copy uploaded at load time.

- Model [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loader-cuda/#model
  Signature: pub const Model = struct
  Summary: Runtime model state: parsed config, the live CUDA context, every weight tensor resident on the GPU, and the still-mapped GGUF file (kept alive for CPU-side embedding dequantization).
  - Model.load [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/loader-cuda/#model-load
    Signature: pub fn load(allocator: std.mem.Allocator, ctx: ?*shim.CudaCtx, path: []const u8) !Model
    Summary: Open + mmap the GGUF at `path`, parse it, extract the config, and upload every tensor to `ctx`.
    Description: The mapping is retained for embedding lookups.
    Param allocator: Owns the GGUF metadata, the tensor list, and the name map.
    Param ctx: Live CUDA context that will own every uploaded weight buffer.
    Param path: Filesystem path to the GGUF model.
    Returns: A fully resident `Model`; call `deinit` to release device + host memory.
  - Model.get [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/loader-cuda/#model-get
    Signature: pub fn get(self: *const Model, name: []const u8) ?*const LoadedTensor
    Summary: Look up a tensor by its exact GGUF name (e.g.
    Description: `"blk.3.attn_q.weight"`).
    Returns: A pointer to the loaded tensor, or null if absent.
  - Model.getLayer [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/loader-cuda/#model-get-layer
    Signature: pub fn getLayer(self: *const Model, layer: u32, suffix: []const u8) ?*const LoadedTensor
    Summary: Look up a per-layer tensor by formatting `"blk.{layer}.{suffix}"`.
    Param layer: Zero-based transformer block index.
    Param suffix: Tensor suffix within the block, e.g. `"attn_q.weight"`.
    Returns: A pointer to the loaded tensor, or null if absent.
  - Model.dequantEmbeddingRow [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/loader-cuda/#model-dequant-embedding-row
    Signature: pub fn dequantEmbeddingRow(self: *const Model, token_id: u32, out: []f32) void
    Summary: Dequantize one row of `token_embd.weight` to f32 on the CPU.
    Description: Reads the raw tensor bytes directly out of the live mapping (no device round-trip). `token_id` is clamped to the last valid row.
    Param token_id: Token whose embedding row to fetch.
    Param out: Destination slice of at least `hidden_dim` f32 values; filled in place.
  - Model.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/loader-cuda/#model-deinit
    Signature: pub fn deinit(self: *Model) void
    Summary: Release device buffers, the GGUF metadata, the name map, and the mapping.

- inspectConfig [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loader-cuda/#inspect-config
  Signature: pub fn inspectConfig(path: []const u8, allocator: std.mem.Allocator) !ModelConfig
  Summary: Inspect a GGUF model's config without uploading any weights to the GPU.
  Description: mmaps the file, parses the header, extracts the `ModelConfig`, then unmaps — used by `zinc --check` to report architecture/dims on the CUDA backend.
  Param path: Filesystem path to the GGUF model.
  Param allocator: Owns the transient GGUF metadata (freed before returning).
  Returns: The parsed `ModelConfig`.

- dequantRow [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loader-cuda/#dequant-row
  Signature: pub fn dequantRow(raw_data: []const u8, row: u32, cols: u32, quant_type: GGMLType, output: []f32) void
  Summary: Dequantize one row of quantized weight data to f32 values.
  Description: Supports f32, f16, Q5_0, Q5_1, Q8_0, Q4_K, Q5_K, Q6_K, and MXFP4. Unsupported types log a warning and zero the output slice.
  Param raw_data: Raw GGUF tensor bytes for the full matrix.
  Param row: Zero-based row index to dequantize.
  Param cols: Number of columns (elements) per row.
  Param quant_type: GGML quantization type describing the on-disk layout.
  Param output: Caller-allocated slice of at least `cols` f32 values; filled in place.

### Module: Loader Metal
URL: https://zolotukhin.ai/zinc/docs/zig-api/loader-metal/
Source: src/model/loader_metal.zig
Code lines: 787
Summary: Metal-specific model loading — zero-copy via mmap + newBufferWithBytesNoCopy.
Overview: This replaces the Vulkan loader's staging-buffer DMA with direct mmap wrapping.

- ModelInspection [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loader-metal/#model-inspection
  Signature: pub const ModelInspection = struct
  Summary: Summary returned by `inspectModel`: config plus file and tensor size statistics.

- LoadedTensor [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loader-metal/#loaded-tensor
  Signature: pub const LoadedTensor = struct
  Summary: A tensor descriptor paired with a Metal buffer holding its weight data (mmap-wrapped or copied).

- Model [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loader-metal/#model
  Signature: pub const Model = struct
  Summary: Runtime model state backed by a memory-mapped GGUF file and zero-copy Metal buffers.
  - Model.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/loader-metal/#model-deinit
    Signature: pub fn deinit(self: *Model) void
    Summary: Release Metal buffers, GGUF metadata, and the backing file mapping.

- residentWeightBytes [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loader-metal/#resident-weight-bytes
  Signature: pub fn residentWeightBytes(model: *const Model) u64
  Summary: Returns the total byte count of model weights that are resident as Metal resources.
  Description: Copied tensor arenas replace their mmap-backed tensors in the GPU-visible working set, so arena bytes are counted once and aliased per-tensor handles are skipped to avoid double-counting.
  Param model: The loaded model whose resident weight size to measure.
  Returns: Total bytes across all Metal-resident weight buffers (arenas + owned tensors).

- inspectConfig [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loader-metal/#inspect-config
  Signature: pub fn inspectConfig(path: []const u8, allocator: std.mem.Allocator) !ModelConfig
  Summary: Parse a GGUF file's metadata and return the derived `ModelConfig` without touching the GPU.
  Description: The file is memory-mapped and unmapped before returning; no Metal resources are created.
  Param path: Filesystem path to the `.gguf` model file.
  Param allocator: Allocator used for GGUF metadata parsing (freed before return).
  Returns: Parsed `ModelConfig` or an error if the file cannot be opened or parsed.

- inspectModel [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loader-metal/#inspect-model
  Signature: pub fn inspectModel(path: []const u8, allocator: std.mem.Allocator) !ModelInspection
  Summary: Parse a GGUF file and return a `ModelInspection` with size statistics and the derived config.
  Description: Computes the total raw byte size of all tensor payloads stored in the file. No GPU resources are created; the file mapping is released before returning.
  Param path: Filesystem path to the `.gguf` model file.
  Param allocator: Allocator used for GGUF metadata parsing (freed before return).
  Returns: `ModelInspection` containing file size, tensor byte count, and `ModelConfig`.

- load [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loader-metal/#load
  Signature: pub fn load( path: []const u8, metal_ctx: ?*shim.MetalCtx, allocator: std.mem.Allocator, ) !Model
  Summary: Load a GGUF model file and return a `Model` backed by zero-copy Metal buffers.
  Description: Each tensor's data is wrapped in a `newBufferWithBytesNoCopy` Metal buffer over the mmap'd file region. For model architectures that benefit from it (e.g. dense Gemma layers), select tensors are copied into pre-allocated Metal arenas to avoid UMA pressure from mixed mmap/Metal page-fault patterns. All weight buffers are registered with an `MTLResidencySet` on macOS 15+ to prevent paging between layers. supported architecture (qwen2, qwen2_moe, qwen35, mistral, mamba, jamba, gemma).
  Param path: Filesystem path to the `.gguf` model file.
  Param metal_ctx: Active Metal context used to create and wrap GPU buffers; must be non-null.
  Param allocator: Allocator for tensor and arena bookkeeping (retained in the returned `Model`).
  Returns: Initialized `Model` or an error if the file cannot be mapped, parsed, or lacks a

### Module: Loader
URL: https://zolotukhin.ai/zinc/docs/zig-api/loader/
Source: src/model/loader.zig
Code lines: 647
Summary: Build runtime model state from GGUF metadata and GPU-resident tensor buffers.
Overview: This module translates an on-disk GGUF file into the normalized model configuration and uploaded tensors consumed by the inference runtime.

- Architecture [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loader/#architecture
  Signature: pub const Architecture = config_mod.Architecture
  Summary: Supported model architectures (re-exported from config.zig).

- ModelConfig [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loader/#model-config
  Signature: pub const ModelConfig = config_mod.ModelConfig
  Summary: Normalized model dimensions and hyperparameters (re-exported from config.zig).

- ModelInspection [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loader/#model-inspection
  Signature: pub const ModelInspection = struct
  Summary: Summary returned by `inspectModel`: config plus file and tensor size statistics.

- LoadedTensor [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loader/#loaded-tensor
  Signature: pub const LoadedTensor = struct
  Summary: A tensor descriptor paired with the GPU buffer that stores its contents.

- isMoEExpertTensor [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loader/#is-mo-eexpert-tensor
  Signature: pub fn isMoEExpertTensor(name: []const u8) bool
  Summary: Return true if this GGUF tensor name designates a fused MoE expert weight tensor.
  Description: Matches the four suffixes emitted by GGUF for sparse-MoE architectures: `ffn_gate_exps.weight`, `ffn_up_exps.weight`, `ffn_down_exps.weight`, and `ffn_down_exps_scale.weight` (Q4_K_M variants only). Dense tensors and non-expert MoE tensors (router gate, attention, embeddings, etc.) are not matched.

- computeOffloadDecision [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loader/#compute-offload-decision
  Signature: pub fn computeOffloadDecision( override: OffloadOverride, total_tensor_bytes: u64, offloadable_tensor_bytes: u64, vram_budget_bytes: u64, ) bool
  Summary: Compute whether MoE expert tensors should be offloaded to host RAM, without mutating any global state.
  Description: Suitable for unit tests and for use by the side-effecting `decideOffloadForLoad` wrapper.
  Param override: Explicit env-var override (.force_on/.force_off) or .auto.
  Param total_tensor_bytes: Total size of all model tensors in bytes.
  Param offloadable_tensor_bytes: Bytes belonging to MoE expert tensors only.
  Param vram_budget_bytes: Reported VRAM capacity in bytes (from Vulkan device).
  Returns: true if expert tensors should be placed in host-visible memory.

- decideOffloadForLoad [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loader/#decide-offload-for-load
  Signature: pub fn decideOffloadForLoad(total_tensor_bytes: u64, offloadable_tensor_bytes: u64, vram_budget_bytes: u64) bool
  Summary: Decide whether to offload MoE expert tensors for the next model load and cache the decision in `offload_state`.
  Description: Honors `ZINC_OFFLOAD_MOE_EXPERTS` if set, otherwise auto-decides: - If the full model fits in VRAM (with headroom for KV/runtime): no offload. - If the model only fits with MoE experts in host RAM: enable offload. - If neither fits: don't enable (let allocation fail with a clear OOM instead of pretending to fit).
  Param total_tensor_bytes: Total size of all model tensors in bytes.
  Param offloadable_tensor_bytes: Bytes belonging to MoE expert tensors only.
  Param vram_budget_bytes: Reported VRAM capacity in bytes (from Vulkan device).
  Returns: true if expert tensors will be placed in host-visible memory.

- offloadEnabled [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loader/#offload-enabled
  Signature: pub fn offloadEnabled() bool
  Summary: Return whether MoE expert tensors should be in host-visible memory for the currently-loaded model.
  Description: Reads the cached decision from `decideOffloadForLoad`. Returns false until a load has happened.

- shouldOffloadToHost [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loader/#should-offload-to-host
  Signature: pub fn shouldOffloadToHost(name: []const u8) bool
  Summary: Return true if this tensor should be allocated in host-visible memory rather than device-local VRAM.
  Description: Returns true only when MoE expert offload is enabled (see `offloadEnabled`) and the tensor name matches an expert weight suffix.
  Param name: GGUF tensor name to classify.
  Returns: true if the tensor belongs to a MoE expert and offload is active.

- Model [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loader/#model
  Signature: pub const Model = struct
  Summary: Runtime model state backed by a memory-mapped GGUF file and uploaded tensor buffers.
  - Model.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/loader/#model-deinit
    Signature: pub fn deinit(self: *Model, instance: *const Instance) void
    Summary: Release tensor buffers, GGUF metadata, and the backing file mapping owned by the model.
    Param self: Model instance to tear down in place.
    Param instance: Unused; accepted for call-site symmetry with other deinit patterns.

- inspectConfig [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loader/#inspect-config
  Signature: pub fn inspectConfig(path: []const u8, allocator: std.mem.Allocator) !ModelConfig
  Summary: Inspect a GGUF file and extract only the normalized model configuration.
  Param path: Path to the GGUF file on disk.
  Param allocator: Allocator used for the parsed metadata structures.
  Returns: A ModelConfig derived from GGUF metadata without uploading tensors to the GPU.

- inspectModel [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loader/#inspect-model
  Signature: pub fn inspectModel(path: []const u8, allocator: std.mem.Allocator) !ModelInspection
  Summary: Inspect a GGUF file and return a `ModelInspection` containing the normalized model config, the on-disk file size, total tensor byte count, offloadable (MoE expert) tensor byte count, tensor count, and metadata key count.
  Description: Does not allocate GPU resources or upload tensors.
  Param path: Path to the GGUF file on disk.
  Param allocator: Allocator used for the parsed GGUF metadata structures.
  Returns: A `ModelInspection` with config and tensor/file size statistics.

- load [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loader/#load
  Signature: pub fn load( path: []const u8, instance: *const Instance, cmd_pool: *const CommandPool, allocator: std.mem.Allocator, ) !Model
  Summary: Load a GGUF model: memory-map the file, parse headers, and DMA tensors to GPU VRAM.
  Param path: Path to the GGUF file on disk.
  Param instance: Active Vulkan instance used for buffer allocation.
  Param cmd_pool: Command pool used for staging copy operations.
  Param allocator: Allocator used for metadata, tensor lists, and temporary state.
  Returns: A fully populated Model with parsed metadata and uploaded tensors.

## Tokenization

Prompt and output text conversion between UTF-8 strings and token IDs used by the decode loop.
URL: https://zolotukhin.ai/zinc/docs/zig-api#tokenization

### Module: Tokenizer
URL: https://zolotukhin.ai/zinc/docs/zig-api/tokenizer/
Source: src/model/tokenizer.zig
Code lines: 1796
Summary: Native BPE tokenizer that reads vocabulary and merge rules from GGUF metadata.
Overview: Implements byte-pair encoding directly in Zig using the tokenizer tables embedded in GGUF model files, eliminating external tokenizer dependencies.

- Tokenizer [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tokenizer/#tokenizer
  Signature: pub const Tokenizer = struct
  Summary: A native BPE tokenizer backed by vocabulary and merge tables from GGUF metadata.

- initFromGGUF [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tokenizer/#init-from-gguf
  Signature: pub fn initFromGGUF(gf: *const gguf.GGUFFile, allocator: std.mem.Allocator) !Tokenizer
  Summary: Initialize a Tokenizer from an open GGUF file.
  Description: Reads `tokenizer.ggml.tokens`, `tokenizer.ggml.merges`, token scores, and special token IDs (BOS, EOS, add-BOS flag) from GGUF metadata. Also builds the `merge_ranks` lookup table so that subsequent `encode` calls are fast.
  Param gf: Parsed GGUF file whose metadata contains the tokenizer tables.
  Param allocator: Used for all owned heap allocations; pass to `deinit` to free.
  Returns: An initialized Tokenizer, or an error if required metadata is absent.

- encode [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tokenizer/#encode
  Signature: pub fn encode(self: *const Tokenizer, text: []const u8) ![]u32
  Summary: Encode UTF-8 text into a sequence of token IDs.
  Description: Applies the appropriate pretokenizer (Gemma-4 chunk splitter, GPT-2 word splitter, or legacy no-split) and then BPE or SentencePiece merges. The returned slice is owned by the caller; free it with `freeEncoded`.
  Param text: UTF-8 input to tokenize; an empty string returns an empty slice.
  Returns: Heap-allocated token ID sequence, or an error on allocation failure.

- freeEncoded [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tokenizer/#free-encoded
  Signature: pub fn freeEncoded(self: *const Tokenizer, tokens: []u32) void
  Summary: Release a token slice returned by `encode`.

- encodePrompt [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tokenizer/#encode-prompt
  Signature: pub fn encodePrompt(self: *const Tokenizer, text: []const u8, allocator: std.mem.Allocator) ![]u32
  Summary: Encode a prompt and prepend BOS when the model expects it.
  Description: The returned slice is allocated with `allocator`, so server routes can use a per-request allocator while the tokenizer keeps owning its internal scratch buffers. Special tokens (e.g. `<|start_header_id|>`) are resolved via `token_to_id` rather than being BPE-encoded character by character.

- eosId [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tokenizer/#eos-id
  Signature: pub fn eosId(self: *const Tokenizer) u32
  Summary: Return the model's end-of-sequence token ID as loaded from GGUF metadata.

- isEndOfGeneration [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tokenizer/#is-end-of-generation
  Signature: pub fn isEndOfGeneration(self: *const Tokenizer, token: u32) bool
  Summary: Whether a sampled token ends the current generation turn.
  Description: Always terminates on the configured EOS. Gemma 4 additionally uses `<eos>=1` and `</s>=212` alongside the primary `<turn|>=106` EOS — we treat those as EOG too when the chat template is Gemma, but not for other tokenizers (Qwen token 1 is a plain `"` character).

- bosId [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tokenizer/#bos-id
  Signature: pub fn bosId(self: *const Tokenizer) u32
  Summary: Return the model's beginning-of-sequence token ID.
  Description: Falls back to `eos_id` when no BOS token was found in GGUF metadata.

- shouldPrependBos [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tokenizer/#should-prepend-bos
  Signature: pub fn shouldPrependBos(self: *const Tokenizer) bool
  Summary: Return true when prompt construction should prepend a BOS token.
  Description: Requires both `prepend_bos` (from GGUF metadata) to be set and a valid `bos_id` to exist; returns false if either condition is absent.

- preparePromptTokens [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tokenizer/#prepare-prompt-tokens
  Signature: pub fn preparePromptTokens(self: *const Tokenizer, raw_tokens: []const u32) ![]u32
  Summary: Wrap a raw token sequence with BOS/EOS according to the GGUF metadata flags.
  Description: Prepends BOS when `shouldPrependBos()` is true and appends EOS when `add_eos_token` is set. Allocates the result with the tokenizer's own allocator; caller is responsible for freeing the returned slice.
  Param raw_tokens: The BPE-encoded token IDs to wrap.
  Returns: A newly allocated slice with optional BOS prefix and EOS suffix.

- decodeToken [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tokenizer/#decode-token
  Signature: pub fn decodeToken(self: *const Tokenizer, token_id: u32, buf: []u8) []const u8
  Summary: Decode a single token ID to UTF-8 text, reversing the GPT-2 byte-to-unicode mapping.
  Description: Handles SentencePiece word-boundary markers (▁ → space) and passes through non-ASCII codepoints (CJK, emoji) verbatim. Returns an empty string for out-of-range token IDs.
  Param token_id: Vocabulary index to decode.
  Param buf: Caller-supplied output buffer; result is a slice into this buffer.
  Returns: UTF-8 bytes for the token, or an empty slice if the ID is out of range.

- ChatTemplateOptions [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tokenizer/#chat-template-options
  Signature: pub const ChatTemplateOptions = struct
  Summary: Options controlling chat template rendering behavior.

- supportsThinkingToggle [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tokenizer/#supports-thinking-toggle
  Signature: pub fn supportsThinkingToggle(self: *const Tokenizer) bool
  Summary: Return whether the model's chat template supports an explicit thinking toggle.

- applyChatTemplate [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tokenizer/#apply-chat-template
  Signature: pub fn applyChatTemplate(self: *const Tokenizer, roles: []const []const u8, contents: []const []const u8, buf: []u8) ![]const u8
  Summary: Format a conversation into a model prompt using the embedded chat template.
  Description: Convenience wrapper around `applyChatTemplateWithOptions` with default options.
  Param roles: Parallel slice of role strings (e.g. "user", "assistant", "system").
  Param contents: Parallel slice of message body strings.
  Param buf: Caller-supplied output buffer that receives the formatted prompt.
  Returns: A slice of `buf` containing the rendered prompt.

- applyChatTemplateWithOptions [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tokenizer/#apply-chat-template-with-options
  Signature: pub fn applyChatTemplateWithOptions(self: *const Tokenizer, roles: []const []const u8, contents: []const []const u8, options: ChatTemplateOptions, buf: []u8) ![]const u8
  Summary: Format a conversation into a model prompt with fine-grained rendering control.
  Description: Dispatches to the appropriate template renderer (ChatML, Llama-3, Gemma, OpenAI-MoE, or generic) based on `detectTemplateKind()`. Supports optional thinking tags, tool definitions, forced tool-call prefills, and generation-prompt suffixes.
  Param roles: Parallel slice of role strings (e.g. "user", "assistant", "system").
  Param contents: Parallel slice of message body strings.
  Param options: Rendering options; see `ChatTemplateOptions` for details.
  Param buf: Caller-supplied output buffer that receives the formatted prompt.
  Returns: A slice of `buf` containing the rendered prompt.

## Decode Planning

Static graph construction and dependency ordering for the per-token compute work that the runtime records and submits.
URL: https://zolotukhin.ai/zinc/docs/zig-api#decode-planning

### Module: Graph
URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/
Source: src/compute/graph.zig
Code lines: 1191
Summary: Represent decode work as a dependency graph that can be topologically ordered.
Overview: Graph builders use this module to describe fused operations, dependencies, and dispatch metadata before any Vulkan command recording happens.

- ExecDomain [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#exec-domain
  Signature: pub const ExecDomain = enum
  Summary: Where a graph node executes: GPU compute, GPU transfer, or CPU host.

- BottleneckKind [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#bottleneck-kind
  Signature: pub const BottleneckKind = enum
  Summary: Classification of the dominant performance bottleneck for a graph node.

- HardwareInfo [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#hardware-info
  Signature: pub const HardwareInfo = struct
  Summary: Hardware parameters used by bottleneck and utilization heuristics.

- OpType [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#op-type
  Signature: pub const OpType = enum
  Summary: Operation types that a compute graph node can represent.
  Description: Each variant maps to one GPU shader dispatch or fused kernel invocation during decode-time execution.

- Node [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#node
  Signature: pub const Node = struct
  Summary: A single operation node in the compute dependency graph.
  Description: Each node carries dispatch metadata (workgroups, push constants) and dependency edges so the graph can be topologically sorted before recording.

- Edge [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#edge
  Signature: pub const Edge = struct
  Summary: Directed dependency edge between two graph nodes.

- OpCount [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#op-count
  Signature: pub const OpCount = struct
  Summary: Count of nodes that share the same operation type.

- CriticalPathNode [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#critical-path-node
  Signature: pub const CriticalPathNode = struct
  Summary: Critical-path node annotated with its dependency depth.

- NodeAnalysis [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#node-analysis
  Signature: pub const NodeAnalysis = struct
  Summary: Per-node structural metrics derived from the dependency graph.

- Hotspot [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#hotspot
  Signature: pub const Hotspot = struct
  Summary: A node ranked among the top contributors to estimated decode time.

- GraphAnalysis [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-analysis
  Signature: pub const GraphAnalysis = struct
  Summary: Computed summary of the graph structure used by visualization and debugging tools.
  - GraphAnalysis.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-analysis-deinit
    Signature: pub fn deinit(self: *GraphAnalysis) void
    Summary: Release the arrays allocated for the analysis result.
    Param self: Graph analysis to tear down in place.

- Graph [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph
  Signature: pub const Graph = struct
  Summary: Static compute graph for a transformer layer or full decode pass.
  - Graph.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-init
    Signature: pub fn init(allocator: std.mem.Allocator, name: []const u8) Graph
    Summary: Initialize an empty graph with a human-readable name.
    Param allocator: Allocator used for node storage.
    Param name: Debug name for logging and diagnostics.
    Returns: A graph ready to accept nodes and dependencies.
  - Graph.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-deinit
    Signature: pub fn deinit(self: *Graph) void
    Summary: Release all graph nodes owned by the graph.
    Param self: Graph to tear down in place.
  - Graph.addNode [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-add-node
    Signature: pub fn addNode(self: *Graph, op: OpType, name: []const u8) !u32
    Summary: Append a node to the graph and assign it the next dense node ID.
    Param self: Graph to append to.
    Param op: Operation kind represented by the new node.
    Param name: Human-readable node label used in logs and diagnostics.
    Returns: The node ID assigned to the appended node.
    Note: IDs are stable for the lifetime of the graph and match insertion order.
  - Graph.setInputs [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-set-inputs
    Signature: pub fn setInputs(self: *Graph, node_id: u32, inputs: []const u32) void
    Summary: Set the input buffer table indices consumed by a node.
    Param self: Graph containing the node to update.
    Param node_id: ID of the node whose inputs should be overwritten.
    Param inputs: Buffer table indices consumed in shader binding order.
    Note: The slice is copied into the node's fixed-size input array.
  - Graph.setOutput [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-set-output
    Signature: pub fn setOutput(self: *Graph, node_id: u32, output: u32) void
    Summary: Set the output buffer table index produced by a node.
    Param self: Graph containing the node to update.
    Param node_id: ID of the node whose output should be overwritten.
    Param output: Buffer table index produced by the node.
  - Graph.setWorkgroups [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-set-workgroups
    Signature: pub fn setWorkgroups(self: *Graph, node_id: u32, x: u32, y: u32, z: u32) void
    Summary: Set the workgroup dimensions that should be used when dispatching a node.
    Param self: Graph containing the node to update.
    Param node_id: ID of the node whose dispatch dimensions should be overwritten.
    Param x: Workgroup count in the X dimension.
    Param y: Workgroup count in the Y dimension.
    Param z: Workgroup count in the Z dimension.
  - Graph.setLayerIndex [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-set-layer-index
    Signature: pub fn setLayerIndex(self: *Graph, node_id: u32, layer_index: ?u32) void
    Summary: Assign a transformer layer index to a node for per-layer diagnostics.
  - Graph.setExecDomain [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-set-exec-domain
    Signature: pub fn setExecDomain(self: *Graph, node_id: u32, domain: ExecDomain) void
    Summary: Override the execution domain for a node (defaults to `gpu_compute`).
  - Graph.setThreadsPerWorkgroup [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-set-threads-per-workgroup
    Signature: pub fn setThreadsPerWorkgroup(self: *Graph, node_id: u32, threads_per_workgroup: u32) void
    Summary: Set the number of threads per workgroup for occupancy estimates.
  - Graph.setCostEstimate [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-set-cost-estimate
    Signature: pub fn setCostEstimate(self: *Graph, node_id: u32, read_bytes: u64, write_bytes: u64, weight_bytes: u64, flops: u64) void
    Summary: Attach byte-traffic and FLOP cost estimates used by the bottleneck heuristics.
    Param self: Graph containing the node to update.
    Param node_id: ID of the node whose cost estimates should be overwritten.
    Param read_bytes: Estimated activation bytes read per dispatch.
    Param write_bytes: Estimated bytes written per dispatch.
    Param weight_bytes: Estimated weight/tensor payload bytes streamed per dispatch.
    Param flops: Approximate floating-point operations performed per dispatch.
  - Graph.setHostSync [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-set-host-sync
    Signature: pub fn setHostSync(self: *Graph, node_id: u32, requires_host_sync: bool) void
    Summary: Mark whether a node requires host-visible synchronization or readback.
  - Graph.setNote [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-set-note
    Signature: pub fn setNote(self: *Graph, node_id: u32, note: ?[]const u8) void
    Summary: Attach an optional static diagnostic note to a node.
  - Graph.setAssumedDecodeSeqLen [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-set-assumed-decode-seq-len
    Signature: pub fn setAssumedDecodeSeqLen(self: *Graph, assumed_decode_seq_len: u32) void
    Summary: Record the sequence length assumed when building decode-time cost estimates.
  - Graph.setHardwareContext [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-set-hardware-context
    Signature: pub fn setHardwareContext(self: *Graph, hardware: HardwareInfo) void
    Summary: Provide hardware parameters used by occupancy and bandwidth heuristics.
  - Graph.addDependency [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-add-dependency
    Signature: pub fn addDependency(self: *Graph, node_id: u32, depends_on: u32) void
    Summary: Declare that one node must execute after another.
    Param self: Graph containing both nodes.
    Param node_id: Node that depends on `depends_on`.
    Param depends_on: Node that must run first.
    Note: Cycles are not rejected here; `topologicalOrder()` detects them later.
  - Graph.topologicalOrder [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-topological-order
    Signature: pub fn topologicalOrder(self: *const Graph, allocator: std.mem.Allocator) ![]u32
    Summary: Compute a valid execution order for the current dependency graph.
    Param self: Graph to sort.
    Param allocator: Allocator used for temporary in-degree tracking and the returned order slice.
    Returns: Node IDs in a valid execution order, or `error.CyclicDependency` when the graph contains a cycle.
  - Graph.nodeCount [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-node-count
    Signature: pub fn nodeCount(self: *const Graph) usize
    Summary: Return the number of nodes currently stored in the graph.
    Param self: Graph to inspect.
    Returns: The number of appended nodes.
  - Graph.analyze [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-analyze
    Signature: pub fn analyze(self: *const Graph, allocator: std.mem.Allocator) !GraphAnalysis
    Summary: Analyze dependency structure for visualization and optimization work.
    Param self: Graph to inspect.
    Param allocator: Allocator used for the returned analysis arrays.
    Returns: A GraphAnalysis containing op counts, edges, node depths, and the longest dependency chain.
  - Graph.writeJsonReport [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-write-json-report
    Signature: pub fn writeJsonReport(self: *const Graph, writer: *std.Io.Writer, allocator: std.mem.Allocator) !void
    Summary: Serialize a graph-analysis JSON payload suitable for custom viewers and scripts.
    Param self: Graph to inspect and serialize.
    Param writer: Destination writer for the JSON payload.
    Param allocator: Allocator used for temporary analysis storage.
  - Graph.writeDot [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-write-dot
    Signature: pub fn writeDot(self: *const Graph, writer: *std.Io.Writer, allocator: std.mem.Allocator) !void
    Summary: Serialize the graph as Graphviz DOT for quick local rendering.
    Param self: Graph to inspect and serialize.
    Param writer: Destination writer for the DOT payload.
    Param allocator: Allocator used for temporary analysis storage.

### Module: Architecture
URL: https://zolotukhin.ai/zinc/docs/zig-api/architecture/
Source: src/model/architecture.zig
Code lines: 995
Summary: Build static decode graphs for the supported model families.
Overview: These graphs describe the logical order of decode-time operations so runtime code can bind buffers and record compute work against a stable structure.

- buildDecodeGraph [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/architecture/#build-decode-graph
  Signature: pub fn buildDecodeGraph(config: *const ModelConfig, allocator: std.mem.Allocator) !Graph
  Summary: Build a compute graph for a single transformer decode step.
  Description: This creates the graph structure; actual buffer bindings are set at runtime.
  Param config: Normalized model dimensions and architecture metadata.
  Param allocator: Allocator used for graph storage.
  Returns: A Graph describing the decode-time op order for the selected architecture.

- buildDecodeGraphDetailed [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/architecture/#build-decode-graph-detailed
  Signature: pub fn buildDecodeGraphDetailed(config: *const ModelConfig, allocator: std.mem.Allocator, gf: ?*const gguf.GGUFFile) !Graph
  Summary: Build a compute graph with per-op weight-size annotations derived from a GGUF file.
  Description: Dispatches to the appropriate architecture-specific builder based on `config.architecture`. from it instead of using float-size approximations.
  Param config: Normalized model dimensions and architecture metadata.
  Param allocator: Allocator used for graph storage.
  Param gf: Optional parsed GGUF file; when non-null, actual tensor byte sizes are read
  Returns: A Graph describing the decode-time op order for the selected architecture.
  Note: Returns `error.UnsupportedArchitecture` if `config.architecture` is `.unknown`.

### Module: Graph
URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/
Source: src/zinc_rt/ir/graph.zig
Code lines: 79
Summary: Shape-static ZINC_RT IR graph builder.
Overview: Graphs contain logical buffers and opcode nodes before any tier lowers them into packets, shaders, or pure Zig calls.

- BufferId [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#buffer-id
  Signature: pub const BufferId = u32
  Summary: Dense index identifying a logical buffer inside a Graph.
  Description: Buffer ids are assigned sequentially by `Graph.addBuffer` starting at 0.

- NodeId [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#node-id
  Signature: pub const NodeId = u32
  Summary: Dense index identifying a node (opcode invocation) inside a Graph.
  Description: Node ids are assigned in insertion order by `Graph.addNode`.

- max_bindings [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#max-bindings
  Signature: pub const max_bindings = 8
  Summary: Maximum number of input or output buffers a single node may bind.
  Description: Picked to keep `BindingList` inline-storable without heap allocation.

- BindingList [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#binding-list
  Signature: pub const BindingList = struct
  Summary: Fixed-capacity list of buffer ids bound to one side of a node.
  Description: Stores up to `max_bindings` entries inline so a `Node` stays POD and trivially copyable through the planner.
  - BindingList.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#binding-list-init
    Signature: pub fn init(values: []const BufferId) !BindingList
    Summary: Build a binding list from a slice of buffer ids.
    Param values: Buffer ids to copy; must contain at most `max_bindings`.
    Returns: A fully populated `BindingList`.
    Note: Returns `error.TooManyBindings` when `values.len > max_bindings`.
  - BindingList.slice [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#binding-list-slice
    Signature: pub fn slice(self: *const BindingList) []const BufferId
    Summary: View the populated prefix of the binding list as a slice.
    Returns: The first `self.len` buffer ids, in insertion order.

- Node [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#node
  Signature: pub const Node = struct
  Summary: Single opcode invocation in the graph.
  Description: Each node references its inputs and outputs by `BufferId`; the opcode itself decides the semantics of those bindings (see `op.Info`).

- Graph [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph
  Signature: pub const Graph = struct
  Summary: Shape-static ZINC_RT IR graph.
  Description: A graph is a flat list of opcode nodes plus a buffer count; lowering passes turn this representation into T-CPU packets, PM4 indirect buffers, or Metal/Vulkan dispatches without mutating the graph itself.
  - Graph.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-init
    Signature: pub fn init(allocator: std.mem.Allocator) Graph
    Summary: Create an empty graph backed by `allocator`.
    Description: tracked as a plain counter and require no per-buffer heap allocation.
    Param allocator: Retained for growing the node array; buffer ids are
    Returns: A zero-buffer, zero-node graph ready for `addBuffer`/`addNode`.
  - Graph.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-deinit
    Signature: pub fn deinit(self: *Graph) void
    Summary: Release the node array and poison the graph value.
    Note: Buffer ids are integers and require no per-buffer release.
  - Graph.addBuffer [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-add-buffer
    Signature: pub fn addBuffer(self: *Graph) BufferId
    Summary: Reserve a new logical buffer and return its id.
    Returns: The freshly allocated `BufferId`, equal to the previous buffer count.
  - Graph.addNode [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-add-node
    Signature: pub fn addNode( self: *Graph, opcode: op.Opcode, inputs: []const BufferId, outputs: []const BufferId, ) !NodeId
    Summary: Append an opcode node with the given input and output bindings.
    Param opcode: Opcode this node executes.
    Param inputs: Buffer ids consumed by the node, in opcode-defined order.
    Param outputs: Buffer ids produced by the node, in opcode-defined order.
    Returns: The `NodeId` of the newly appended node.
    Note: Fails with `error.TooManyBindings` when either slice exceeds `max_bindings`.
  - Graph.verify [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/graph/#graph-verify
    Signature: pub fn verify(self: *const Graph) !void
    Summary: Structural sanity check: graph is non-empty, all bindings resolve, and every non-barrier/stream_out node produces at least one output.
    Description: `error.UnknownOutputBuffer`, or `error.NodeWithoutOutput` on failure.
    Returns: `error.EmptyGraph`, `error.UnknownInputBuffer`,

### Module: Op
URL: https://zolotukhin.ai/zinc/docs/zig-api/op/
Source: src/zinc_rt/ir/op.zig
Code lines: 99
Summary: ZINC_RT IR opcode definitions.
Overview: This table mirrors Appendix B of the design and gives each opcode stable metadata for verification, lowering, and T-CPU dispatch.

- Stage [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/op/#stage
  Signature: pub const Stage = enum
  Summary: Which inference stage an opcode participates in.
  Description: `decode` ops run during single-token autoregressive steps, `prefill` ops run during the batched prompt-ingestion phase, and `both` ops are shared between the two paths (e.g. RMS norm, RoPE).

- Milestone [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/op/#milestone
  Signature: pub const Milestone = enum
  Summary: Roadmap milestone in which the opcode becomes mandatory.
  Description: `m0` is the minimum viable decode set; later milestones add fused kernels, prefill batching, request-state I/O, and verification ops.

- Opcode [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/op/#opcode
  Signature: pub const Opcode = enum(u8)
  Summary: ZINC_RT IR opcode table.
  Description: Each variant maps onto Appendix B of the runtime design; metadata such as the human-readable name, stage, and milestone live in `info`.

- Info [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/op/#info
  Signature: pub const Info = struct
  Summary: Static metadata for an opcode.
  Description: Pairs the IR enum with its canonical printable name, the stage it targets, and the milestone in which it must be implemented.

- info [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/op/#info
  Signature: pub fn info(opcode: Opcode) Info
  Summary: Look up the static metadata record for an opcode.
  Description: never traps at runtime.
  Param opcode: IR opcode to describe.
  Returns: The matching `Info` entry; the switch is exhaustive so this

- name [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/op/#name
  Signature: pub fn name(opcode: Opcode) []const u8
  Summary: Canonical printable name for an opcode (e.g.
  Description: `"FLASH_ATTN"`).
  Param opcode: IR opcode to name.
  Returns: The `Info.name` string, suitable for logging and golden traces.

- fromName [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/op/#from-name
  Signature: pub fn fromName(value: []const u8) ?Opcode
  Summary: Parse an opcode from its canonical name or Zig identifier.
  Description: Accepts either the printable `Info.name` (case-sensitive) or the Zig enum field name (case-insensitive), so both `"FLASH_ATTN"` and `"flash_attn"` resolve to `Opcode.flash_attn`.
  Param value: Candidate opcode spelling.
  Returns: The matching opcode, or `null` when no variant matches.

- isM0 [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/op/#is-m0
  Signature: pub fn isM0(opcode: Opcode) bool
  Summary: Check whether an opcode is part of the M0 minimum-viable decode set.
  Param opcode: IR opcode to query.
  Returns: `true` when `info(opcode).milestone == .m0`.

### Module: Verify
URL: https://zolotukhin.ai/zinc/docs/zig-api/verify/
Source: src/zinc_rt/ir/verify.zig
Code lines: 4
Summary: ZINC_RT IR verifier entrypoints.
Overview: Verification stays separate from graph construction so future passes can reject malformed shapes and bindings before any backend executes them.

- graph [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/verify/#graph
  Signature: pub fn graph(ir: *const graph_mod.Graph) !void
  Summary: Run structural verification over an IR graph.
  Description: Thin wrapper around `Graph.verify` so callers depend on this module rather than reaching into the graph type directly; future passes will add shape and type checks here without touching graph construction.
  Param ir: Graph to inspect; not mutated.
  Returns: Propagates any verification error from `Graph.verify`.

## Inference Runtime

Decode state, pipeline ownership, command recording, and token sampling inside the active inference loop.
URL: https://zolotukhin.ai/zinc/docs/zig-api#inference-runtime

### Module: Bench Hot Decode
URL: https://zolotukhin.ai/zinc/docs/zig-api/bench-hot-decode/
Source: src/bench_hot_decode.zig
Code lines: 1003
Summary: Hot-path decode kernel microbenchmarks.
Overview: Measures per-dispatch GPU latency, memory bandwidth, and VRAM utilisation for individual compute kernels (DMMV, SSM delta-net) in isolation. Run via `zig build hot-bench -Doptimize=ReleaseFast`.

- main [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/bench-hot-decode/#main
  Signature: pub fn main() !void
  Summary: Run the hot-decode microbenchmark suite against the selected model and kernels.

### Module: Bench Support
URL: https://zolotukhin.ai/zinc/docs/zig-api/bench-support/
Source: src/bench_support.zig
Code lines: 26
Summary: Shared helpers for benchmark and standalone runner entrypoints.
Overview: This module re-exports the Metal runtime pieces that the benchmark tools need and centralizes the GPU-process-lock error path so the small bench binaries do not duplicate server/runtime boilerplate.

- metal_device [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/bench-support/#metal-device
  Signature: pub const metal_device = @import("metal/device.zig")
  Summary: Metal device initialization and capability queries (MTLDevice wrapper).

- metal_loader [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/bench-support/#metal-loader
  Signature: pub const metal_loader = @import("model/loader_metal.zig")
  Summary: Model loader that maps GGUF weights onto Metal buffers.

- metal_buffer [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/bench-support/#metal-buffer
  Signature: pub const metal_buffer = @import("metal/buffer.zig")
  Summary: Metal buffer allocation and management utilities.

- metal_command [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/bench-support/#metal-command
  Signature: pub const metal_command = @import("metal/command.zig")
  Summary: Metal command queue and command buffer submission helpers.

- kernel_timing [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/bench-support/#kernel-timing
  Signature: pub const kernel_timing = @import("metal/kernel_timing.zig")
  Summary: Per-kernel Metal dispatch timing probe for profiling individual GPU kernels.

- metal_pipeline [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/bench-support/#metal-pipeline
  Signature: pub const metal_pipeline = @import("metal/pipeline.zig")
  Summary: Metal compute pipeline state cache and compilation helpers.

- metal_c [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/bench-support/#metal-c
  Signature: pub const metal_c = @import("metal/c.zig")
  Summary: Raw Objective-C/Metal C shim types and bindings.

- gguf [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/bench-support/#gguf
  Signature: pub const gguf = @import("model/gguf.zig")
  Summary: GGUF file parser for reading quantized model weights and metadata.

- tokenizer_mod [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/bench-support/#tokenizer-mod
  Signature: pub const tokenizer_mod = @import("model/tokenizer.zig")
  Summary: BPE tokenizer encode and decode for text pre/post-processing.

- forward_metal [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/bench-support/#forward-metal
  Signature: pub const forward_metal = @import("compute/forward_metal.zig")
  Summary: Metal forward-pass runtime that runs the full model inference graph.

- process_lock [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/bench-support/#process-lock
  Signature: pub const process_lock = @import("gpu/process_lock.zig")
  Summary: Cross-process GPU ownership lock preventing two zinc processes from sharing a GPU.

- reportGpuProcessLockError [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/bench-support/#report-gpu-process-lock-error
  Signature: pub fn reportGpuProcessLockError(err: anyerror, backend: process_lock.Backend, device_index: u32) noreturn
  Summary: Log a user-facing GPU-process-lock error and terminate the benchmark binary.
  Description: Prints a human-readable message to stderr explaining why the lock could not be acquired, then calls `std.process.exit(1)`.
  Description: dedicated "stop the other instance" message; all other errors fall back to a generic failure message.
  Param err: The lock-acquisition error; `error.GpuAlreadyReserved` gets a
  Param backend: The GPU backend whose lock failed (used in the log message).
  Param device_index: Index of the GPU device that could not be locked (used in the log message).

### Module: Forward Cuda Gemma
URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda-gemma/
Source: src/compute/forward_cuda_gemma.zig
Code lines: 1738
Summary: CUDA forward pass for the dense gemma4 transformer (Gemma 4 31B-it).
Overview: Effort 22 — completes the 5/5 catalog on the 4090. Separate from forward_cuda.zig (qwen35/qwen36 hybrid-SSM family) because gemma4 is a plain transformer with a different per-layer geometry: sliding-window attention on a period-6 pattern (5 SWA + 1 full), per-layer head dims (256 SWA / 512 full) and KV-head counts (16 SWA / 4 full), per-head Q/K RMS norm + per-head V RMS normalize, four norms per layer (pre/post attn + pre/post ffn), GeGLU FFN, a learned per-layer output scale, scaled token embeddings, and a tied LM head.
Overview: Norm convention: the gemma RMSNorm `(1 + weight)` offset is baked into the GGUF weights at conversion (confirmed: attn_q_norm ≈ 1.0234), so every gemma norm reuses the standard `rms_norm` kernel; V uses `rms_norm_noweight`.
Overview: Attention scale: gemma4 sets f_attention_scale = 1.0 (no 1/sqrt(d) scaling). Final-logit soft-cap is monotonic, so it does not change the greedy argmax and is intentionally skipped here (correctness-first bring-up).

- ForwardGemma [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda-gemma/#forward-gemma
  Signature: pub const ForwardGemma = struct
  - ForwardGemma.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda-gemma/#forward-gemma-init
    Signature: pub fn init(allocator: std.mem.Allocator, model: *loader.Model, max_ctx: u32) !ForwardGemma
  - ForwardGemma.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda-gemma/#forward-gemma-deinit
    Signature: pub fn deinit(self: *ForwardGemma) void
  - ForwardGemma.decodeStep [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda-gemma/#forward-gemma-decode-step
    Signature: pub fn decodeStep(self: *ForwardGemma, token: u32, pos: u32, run_layers: bool) !u32
    Summary: One greedy decode step for `token` at sequence position `pos`.
  - ForwardGemma.prefillStep [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda-gemma/#forward-gemma-prefill-step
    Signature: pub fn prefillStep(self: *ForwardGemma, token: u32, pos: u32) !void
    Summary: Prefill helper (mirrors ForwardCuda.prefillStep): run every layer to build the KV cache, but SKIP the tail rms_norm + LM head + argmax — a prompt-internal token's logits are never read.
    Description: Saves the vocab-sized head matvec on T-1 of the T prompt tokens; the MoE gemma model (small active forward, full head) benefits most. Async layer ops drained here; bit-identical generation.
  - ForwardGemma.prefillBatched [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda-gemma/#forward-gemma-prefill-batched
    Signature: pub fn prefillBatched(self: *ForwardGemma, tokens: []const u32) !u32
    Summary: Batched dense-gemma prefill: process ALL T prompt tokens at once, reading each weight ONCE for all tokens via the gemm_*_tiled_v2 register-blocked GEMMs (5.9× over the per-token matvec). Returns the last token's argmax (= the first generated token), exactly like running prefillStep on tokens [0..T-1] then decodeStep on the last. ADDITIVE: builds its own token-major scratch and never touches the single-token decode path.
    Description: Phase-1 scope is the DENSE gemma-31b (n_experts==0). Phase-2 cycle 1 adds the 26b MoE: its ATTENTION block is the SAME structure as the dense model, so it shares the batched attention path (GEMM Q/K/V/O + batched causal attn + batched norm/RoPE/KV-write) — bit-identical to the per-token attentionLayer. Its routed-expert FFN is still LOOPED per token (the existing single-token moeFfnBlock, fed each token's hidden slice via an alias-swap) because the FFN is position-independent → looping it is output-identical; full batched-expert routing (group T tokens by expert) is a later cycle.
  - ForwardGemma.decodeBatch [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda-gemma/#forward-gemma-decode-batch
    Signature: pub fn decodeBatch(self: *ForwardGemma, tokens: []const u32, positions: []const u32, slots: []const u32, out_tokens: []u32) !void
    Summary: Batched DECODE step (DENSE gemma only): advance B independent sequences by ONE token each in a SINGLE B-row forward. The projections + FFN reuse the batched-prefill GEMM path — `gemmDispatch`/`ffnBlockBatched` read each weight ONCE for all B rows (the launch / weight-bandwidth amortization that makes batching a throughput win). The attention inner (per-head V/Q/K norm + RoPE + KV-write + causal softmax) LOOPS per row through the proven single-token kernels (`rms_norm_rope_qkv` / `gemma_attention`) against each sequence's OWN KV slot at its OWN position — so row b attends over slot `slots[b]`'s history [0..positions[b]] only. Fusing that per-row loop into one batched-seq attention kernel is sub-step 1c (a perf step; the looped form here is already correct for mixed positions). ADDITIVE — the production `decodeStep` / `prefillBatched` paths are untouched.
    Description: Requires `allocSlotKv(n_slots, slot_ctx)` first, with n_slots > max(slots) and slot_ctx > max(positions). Each sequence b's slot must already hold its KV history for [0..positions[b]-1] (written by prior `decodeBatch` calls — e.g. a per-token B=1 prefill into the slot). Writes b's new K/V at its slot.
    Description: tokens[b] input token for sequence b this step positions[b] sequence b's current position (slot holds [0..pos-1]) slots[b] sequence b's KV slot index out_tokens[b] greedy argmax for sequence b (caller advances pos + feeds back)
  - ForwardGemma.allocSlotKv [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda-gemma/#forward-gemma-alloc-slot-kv
    Signature: pub fn allocSlotKv(self: *ForwardGemma, n_slots: u32, slot_ctx: u32) !void
    Summary: Allocate slot-based KV for `n_slots` concurrent sequences of up to `slot_ctx` positions each.
    Description: ADDITIVE: a fresh per-layer allocation that never aliases or touches the production single-sequence kv_k/kv_v. The batched-decode path (sub-steps 1b/1c) writes/reads it via `slotKvOffsetBytes`; the production decodeStep is unchanged. Idempotent — frees any prior slot KV first. Sub-step 1a only allocates + smoke-tests it.
  - ForwardGemma.freeSlotKv [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda-gemma/#forward-gemma-free-slot-kv
    Signature: pub fn freeSlotKv(self: *ForwardGemma) void
  - ForwardGemma.slotKvOffsetBytes [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda-gemma/#forward-gemma-slot-kv-offset-bytes
    Signature: pub fn slotKvOffsetBytes(self: *const ForwardGemma, L: u32, slot: u32, pos: u32) usize
    Summary: Byte offset of sequence-slot `slot`'s K/V for position `pos` in layer `L`'s slot KV buffer: (slot*slot_ctx + pos)*kv_dim(L)*sizeof(f32).
    Description: This is the exact indexing the 1c per-sequence kv-write + slot attention kernels use.
  - ForwardGemma.slotKvSmoke [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda-gemma/#forward-gemma-slot-kv-smoke
    Signature: pub fn slotKvSmoke(self: *ForwardGemma) !bool
    Summary: Sub-step 1a plumbing smoke: prove the slot-KV offset arithmetic round-trips and that distinct (slot,pos) pairs map to NON-overlapping device regions.
    Description: Writes a sentinel into (slot 0, pos 0) and a distinct pattern into the LAST (slot, pos) of layer 0's K cache, reads both back, and checks neither write clobbered the other. Returns true on success. Requires allocSlotKv first.
  - ForwardGemma.attentionLayerPub [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda-gemma/#forward-gemma-attention-layer-pub
    Signature: pub fn attentionLayerPub(self: *ForwardGemma, L: u32, pos: u32) !void
  - ForwardGemma.ffnLayerPub [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda-gemma/#forward-gemma-ffn-layer-pub
    Signature: pub fn ffnLayerPub(self: *ForwardGemma, L: u32) !void
    Summary: FFN block dispatched exactly as decodeStep: routed MoE when this layer carries a router, dense GeGLU otherwise.
  - ForwardGemma.layerOutScalePub [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda-gemma/#forward-gemma-layer-out-scale-pub
    Signature: pub fn layerOutScalePub(self: *ForwardGemma, L: u32) !void
  - ForwardGemma.readHidden [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda-gemma/#forward-gemma-read-hidden
    Signature: pub fn readHidden(self: *ForwardGemma, out: []f32) void
  - ForwardGemma.readLogits [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda-gemma/#forward-gemma-read-logits
    Signature: pub fn readLogits(self: *ForwardGemma, out: []f32) void

### Module: Forward Cuda
URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda/
Source: src/compute/forward_cuda.zig
Code lines: 2725
Summary: CUDA forward pass for the dense `qwen35` hybrid-SSM model (Qwen 3.5 9B).
Overview: M2 bring-up — incremental greedy decode of a single token on NVIDIA. The CUDA backend modules (device/buffer/pipeline/command) and the kernel library (`src/shaders/cuda/kernels.cu`, NVRTC-compiled) are orchestrated here into a real forward pass. Weights upload VERBATIM-quantized (Q4_K/Q5_K/Q6_K/Q8_0 blocks) via loader_cuda and are dequantized inside the DMMV kernels.
Overview: Layer schedule (qwen35, full_attention_interval=4): layer L is full attention when ((L+1) % 4 == 0) → L in {3,7,11,15,19,23,27,31}; the other 24 layers are gated-delta-net SSM. Every layer is followed by a SwiGLU FFN block.

- ForwardCuda [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda/#forward-cuda
  Signature: pub const ForwardCuda = struct
  Summary: Per-token GPU forward state for qwen35 greedy decode.
  - ForwardCuda.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda/#forward-cuda-init
    Signature: pub fn init(allocator: std.mem.Allocator, model: *loader.Model, max_ctx: u32) !ForwardCuda
    Summary: Compile kernels, allocate every device buffer, upload inv_freq + sinks, zero the KV cache and SSM state.
  - ForwardCuda.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda/#forward-cuda-deinit
    Signature: pub fn deinit(self: *ForwardCuda) void
  - ForwardCuda.allocSlotState [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda/#forward-cuda-alloc-slot-state
    Signature: pub fn allocSlotState(self: *ForwardCuda, n_slots: u32, slot_ctx: u32) !void
    Summary: Allocate per-sequence slot state for `n_slots` concurrent sequences, each with up to `slot_ctx` positions.
    Description: Attn layers get slot KV; ssm layers get per-slot conv + recurrent state (zero-initialised). Additive — production single-sequence buffers are untouched. Re-callable (frees first).
  - ForwardCuda.freeSlotState [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda/#forward-cuda-free-slot-state
    Signature: pub fn freeSlotState(self: *ForwardCuda) void
  - ForwardCuda.slotKvOffsetBytes [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda/#forward-cuda-slot-kv-offset-bytes
    Signature: pub fn slotKvOffsetBytes(self: *const ForwardCuda, slot: u32, pos: u32) usize
    Summary: Byte offset of slot `slot`'s K/V for position `pos` in attn layer `L`'s slot KV: (slot*slot_ctx + pos)*kv_dim*sizeof(f32).
    Description: The future per-seq kv-write + slot attention kernels (4b/4c) will use this exact indexing.
  - ForwardCuda.slotConvOffsetBytes [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda/#forward-cuda-slot-conv-offset-bytes
    Signature: pub fn slotConvOffsetBytes(self: *const ForwardCuda, slot: u32) usize
    Summary: Byte offset of slot `slot`'s conv ring (ssm layer): slot*conv_state_len*f4.
  - ForwardCuda.slotStateOffsetBytes [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda/#forward-cuda-slot-state-offset-bytes
    Signature: pub fn slotStateOffsetBytes(self: *const ForwardCuda, slot: u32) usize
    Summary: Byte offset of slot `slot`'s recurrent state (ssm layer): slot*ssm_state_len*f4.
  - ForwardCuda.resetSlot [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda/#forward-cuda-reset-slot
    Signature: pub fn resetSlot(self: *ForwardCuda, slot: u32) !void
    Summary: Effort 28 increment 4 (qwen serving): zero a REUSED slot's SSM conv ring + recurrent state so a new request prefilling from pos=0 into this slot starts from clean state.
    Description: The serving engine reuses slots across requests (nslots < concurrent clients) and qwen's SSM state is ACCUMULATED (not position-indexed), so without this a reused slot inherits the prior request's recurrent state → corruption. The attention slot KV needs NO reset (it is position-indexed and overwritten on prefill; reads never reach beyond the current sequence's positions — same reason gemma's slot KV reuses cleanly). No-op if slot state is unallocated. Call on ADMIT, before per-token prefill.
  - ForwardCuda.slotStateSmoke [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda/#forward-cuda-slot-state-smoke
    Signature: pub fn slotStateSmoke(self: *ForwardCuda) !bool
    Summary: Sub-step 4a plumbing smoke: prove the slot-offset arithmetic round-trips and that distinct slots map to NON-overlapping device regions for BOTH the attention KV and the SSM conv + recurrent state.
    Description: Requires allocSlotState with n_slots >= 2 (so slot 0 and slot n_slots-1 differ). Returns true on success.
  - ForwardCuda.resetState [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda/#forward-cuda-reset-state
    Signature: pub fn resetState(self: *ForwardCuda) !void
    Summary: Reset the production single-sequence recurrent state to a fresh-process start: zero every ssm layer's conv ring + recurrent state and clear the per-layer conv offset.
    Description: The attention KV cache needs no reset — it is position-indexed and each sequence overwrites from pos 0, reading only what it wrote. Used by the batch harness to make the per-sequence SERIAL reference truly single-sequence (without this, the unindexed SSM recurrent state leaks from one reference sequence into the next). Additive — never called on the real decode/prefill path; that path runs one sequence/process.
  - ForwardCuda.decodeStep [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda/#forward-cuda-decode-step
    Signature: pub fn decodeStep(self: *ForwardCuda, token: u32, pos: u32, run_layers: bool) !u32
    Summary: Run one greedy decode step for `token` at sequence position `pos`, returning the argmax token id.
    Description: v0: embed → final rms_norm → LM head → argmax (layers are gated by `run_layers`).
  - ForwardCuda.prefillStep [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda/#forward-cuda-prefill-step
    Signature: pub fn prefillStep(self: *ForwardCuda, token: u32, pos: u32) !void
    Summary: Prefill helper: run every layer (build the KV cache) but SKIP the tail rms_norm + LM head + argmax.
    Description: A prompt-internal token's logits are never used — only the final prompt token's argmax seeds generation — so the (vocab x n_embd) head matvec is pure waste on T-1 of the T prompt tokens. It is a large share for the MoE models, whose active per-token forward is small next to the full-vocab head. The async layer ops are drained here (waitPending) so the ring is freed each token; bit-identical generation.
  - ForwardCuda.prefillBatched [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda/#forward-cuda-prefill-batched
    Signature: pub fn prefillBatched(self: *ForwardCuda, tokens: []const u32) !u32
  - ForwardCuda.prefillBatchedSlot [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda/#forward-cuda-prefill-batched-slot
    Signature: pub fn prefillBatchedSlot(self: *ForwardCuda, tokens: []const u32, slot: u32) !u32
    Summary: Batched prefill that writes KV cache + SSM state into the given slot's per-sequence region (instead of the single-seq scratch).
    Description: Used by the serve engine so server-mode prefill gets the 5× batched-GEMM speedup instead of falling back to per-token decodeBatch (B=1).
  - ForwardCuda.decodeBatch [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda/#forward-cuda-decode-batch
    Signature: pub fn decodeBatch(self: *ForwardCuda, tokens: []const u32, positions: []const u32, slots: []const u32, out: []u32) !void
  - ForwardCuda.attentionLayerPub [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda/#forward-cuda-attention-layer-pub
    Signature: pub fn attentionLayerPub(self: *ForwardCuda, L: u32, pos: u32) !void
  - ForwardCuda.ssmLayerPub [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda/#forward-cuda-ssm-layer-pub
    Signature: pub fn ssmLayerPub(self: *ForwardCuda, L: u32) !void
  - ForwardCuda.ffnBlockPub [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda/#forward-cuda-ffn-block-pub
    Signature: pub fn ffnBlockPub(self: *ForwardCuda, L: u32) !void
  - ForwardCuda.readHidden [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda/#forward-cuda-read-hidden
    Signature: pub fn readHidden(self: *ForwardCuda, out: []f32) void
    Summary: Download the current hidden state (for sanity checks).
  - ForwardCuda.readLogits [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-cuda/#forward-cuda-read-logits
    Signature: pub fn readLogits(self: *ForwardCuda, out: []f32) void
    Summary: Download the top of the logits buffer (for top-k reporting).

### Module: Forward Metal
URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/
Source: src/compute/forward_metal.zig
Code lines: 36710
Summary: Metal inference engine — decode loop for Apple Silicon.
Overview: This is the Metal equivalent of forward.zig (Vulkan). Uses MSL compute shaders dispatched via the Metal shim.

- CommandEncoderMode [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#command-encoder-mode
  Signature: pub const CommandEncoderMode = metal_command.CommandEncoderMode
  Summary: Command-encoder mode re-export used by runtime init options.

- runtime_context_cap [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#runtime-context-cap
  Signature: pub const runtime_context_cap: u32 = 262144
  Summary: Upper bound on the Metal KV-cache allocation: we still honour the model's architectural context length and the unified-memory budget, but we refuse to allocate more tokens than this in one block to keep allocation latency and staging buffers sane.
  Description: Callers that already right-sized `cfg.context_length` from the device budget (see `memory_plan.autoContextTokensForDeviceBudget`) see this as a soft safety net rather than the primary limit.

- DecodeState [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#decode-state
  Signature: pub const DecodeState = struct
  Summary: Runtime state for the decode loop.
  - DecodeState.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#decode-state-init
    Signature: pub fn init(allocator: std.mem.Allocator) DecodeState
    Summary: Initialize decode state for a fresh Metal generation request.
  - DecodeState.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#decode-state-deinit
    Signature: pub fn deinit(self: *DecodeState) void
    Summary: Release the generated-token buffer owned by this decode state.

- GenerateMetrics [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#generate-metrics
  Signature: pub const GenerateMetrics = struct
  Summary: Metrics from generateWithMetrics: prefill/decode token counts, timing, and throughput.

- GenerateResult [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#generate-result
  Signature: pub const GenerateResult = struct
  Summary: Output tokens and performance metrics from a generation run.
  - GenerateResult.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#generate-result-deinit
    Signature: pub fn deinit(self: *GenerateResult, allocator: std.mem.Allocator) void
    Summary: Free the generated token slice returned by `generateWithMetrics`.

- SamplingParams [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#sampling-params
  Signature: pub const SamplingParams = struct
  Summary: Token sampling parameters: temperature, top-k, top-p, and repetition penalty.
  - SamplingParams.requiresLogitsReadback [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#sampling-params-requires-logits-readback
    Signature: pub fn requiresLogitsReadback(self: @This()) bool
    Summary: Return whether sampling settings require CPU-visible logits instead of greedy argmax.

- InitOptions [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#init-options
  Signature: pub const InitOptions = struct
  Summary: Options for `InferenceEngine.init`: profiling, debug validation, KV cache, and dispatch tuning.

- RuntimeProfile [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#runtime-profile
  Signature: pub const RuntimeProfile = struct
  Summary: Per-request profiling counters for dispatch, barrier, and timing breakdown.

- attentionLayerCount [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#attention-layer-count
  Signature: pub fn attentionLayerCount(cfg: ModelConfig) u32
  Summary: Return the number of full-attention (non-SSM) transformer layers in the model.
  Param cfg: Model configuration supplying `n_layers` and the full-attention interval.
  Returns: Count of layers that use full multi-head attention; 0 for pure-SSM models.

- defaultKvCacheQ8Enabled [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#default-kv-cache-q8-enabled
  Signature: pub fn defaultKvCacheQ8Enabled(config: ModelConfig, debug_validation_enabled: bool) bool
  Summary: Return whether Q8 KV cache quantization should be enabled by default for this model.
  Description: is available for numerical validation. gpt-oss (SwiGLU sensitivity) and Gemma4 with SWA (ISWA rotation path not yet ported).
  Param config: Model configuration used to check architecture and key-value dimensions.
  Param debug_validation_enabled: When true, always returns false so the unquantized cache
  Returns: True when the architecture and dimensions support Q8 KV cache; false for

- kvCacheBytesPerToken [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#kv-cache-bytes-per-token
  Signature: pub fn kvCacheBytesPerToken(config: ModelConfig, q8_enabled: bool) u64
  Summary: Return the bytes consumed per token in the KV cache.
  Description: otherwise returns the unquantized f32 size.
  Param config: Model configuration providing `n_kv_heads` and `head_dim`.
  Param q8_enabled: When true, returns the Q8_0 packed size (34 bytes per 32 floats);
  Returns: Bytes per KV-cache slot for a single token position.

- InferenceEngine [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#inference-engine
  Signature: pub const InferenceEngine = struct
  Summary: Metal inference engine — owns GPU buffers, pipelines, and KV cache.
  - InferenceEngine.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#inference-engine-init
    Signature: pub fn init( model: *const metal_loader.Model, device: *const metal_device.MetalDevice, allocator: std.mem.Allocator, options: InitOptions, ) !InferenceEngine
    Summary: Initialize the Metal inference engine, allocating GPU buffers and compiling pipelines.
  - InferenceEngine.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#inference-engine-deinit
    Signature: pub fn deinit(self: *InferenceEngine) void
    Summary: Release all GPU buffers, pipelines, and associated resources.
  - InferenceEngine.sampleGreedy [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#inference-engine-sample-greedy
    Signature: pub fn sampleGreedy(self: *const InferenceEngine) u32
    Summary: Sample the next token greedily (argmax over logits).
  - InferenceEngine.sample [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#inference-engine-sample
    Signature: pub fn sample(self: *const InferenceEngine, history: []const u32, params: SamplingParams, random: std.Random) u32
    Summary: Sample next token using temperature, top-k, top-p, and repetition penalty.
    Description: Falls back to greedy if parameters are near-default or buffers are private.
  - InferenceEngine.enableLogitsReadback [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#inference-engine-enable-logits-readback
    Signature: pub fn enableLogitsReadback(self: *InferenceEngine) void
  - InferenceEngine.resetRequestState [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#inference-engine-reset-request-state
    Signature: pub fn resetRequestState(self: *InferenceEngine, requested_context_tokens: u32) !void
    Summary: Reset position, profiling counters, and SSM state for a new request.
  - InferenceEngine.prefillBatch [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#inference-engine-prefill-batch
    Signature: pub fn prefillBatch(self: *InferenceEngine, state: *DecodeState, prompt_tokens: []const u32) !void
    Summary: Run prompt prefill in token-major order, processing one token through all layers at a time.
    Description: Uses a queued async-submit path for short prompts when available; falls back to sequential `commitAndWait` per token otherwise. Callers that want the layer-major batched path should use `prefillBatched` instead. engine's internal position (stale or mismatched state).
    Note: Returns `error.ContextLengthExceeded` if the prompt would overflow the KV cache.
    Note: Returns `error.KvStateNotAvailable` if `state.position` does not match the
  - InferenceEngine.prefillBatched [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#inference-engine-prefill-batched
    Signature: pub fn prefillBatched(self: *InferenceEngine, state: *DecodeState, prompt_tokens: []const u32) !void
    Summary: Experimental batched prompt prefill gated by `ZINC_BATCHED_PREFILL`.
    Description: Processes all prompt tokens in a single batched forward pass using the gemm_q4k / gemm_q6k / rope_batched / flash_attn_batched shaders — the weight matrix for each projection is read once for the whole prompt. Falls back to the per-token `prefillBatch` when the env flag is off or when the model architecture is outside the supported slice (see `canUseBatchedPrefill`). Supports both fresh prefill (state.position==0) and prefix reuse (state.position>0) — in the latter case, the batched pass extends the KV cache at offset `state.position` and flash attention causal masking is computed relative to that offset. With `ZINC_BATCHED_PREFILL=validate` the batched path runs first, then the per-token path is replayed on a fresh state and the last-token logits are diffed; max abs diff is logged and a warning is emitted if it exceeds 1e-3.
  - InferenceEngine.decodeStep [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#inference-engine-decode-step
    Signature: pub fn decodeStep(self: *InferenceEngine, state: *DecodeState, token_id: u32) !void
    Summary: Advance one autoregressive decode step from the given input token.
  - InferenceEngine.enableProfiling [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#inference-engine-enable-profiling
    Signature: pub fn enableProfiling(self: *InferenceEngine) !void
    Summary: Enable request-level profiling counters for subsequent decode work.
  - InferenceEngine.logRequestProfileSummary [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#inference-engine-log-request-profile-summary
    Signature: pub fn logRequestProfileSummary(self: *const InferenceEngine, label: []const u8, prompt_tokens: usize, completion_tokens: u32) void
    Summary: Log the collected Metal profiling summary for the current request to the scoped logger.
    Description: Does nothing when profiling was not enabled via `enableProfiling`.
    Param label: Short identifier string included in every log line (e.g. model name).
    Param prompt_tokens: Number of prompt tokens processed during prefill.
    Param completion_tokens: Number of tokens generated during decode.

- dequantRow [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#dequant-row
  Signature: pub fn dequantRow(raw_data: []const u8, row: u32, cols: u32, quant_type: GGMLType, output: []f32) void
  Summary: Dequantize one row of quantized weight data to f32 values.
  Description: Supports f32, f16, Q5_0, Q5_1, Q8_0, Q4_K, Q5_K, Q6_K, and MXFP4. Unsupported types log a warning and zero the output slice.
  Param raw_data: Raw GGUF tensor bytes for the full matrix.
  Param row: Zero-based row index to dequantize.
  Param cols: Number of columns (elements) per row.
  Param quant_type: GGML quantization type describing the on-disk layout.
  Param output: Caller-allocated slice of at least `cols` f32 values; filled in place.

- topKSoftmaxWeight [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#top-ksoftmax-weight
  Signature: pub fn topKSoftmaxWeight(logits: []const f32, k: u32, out_ids: []u32, out_weights: []f32) void
  Summary: Select the top-k entries by raw logit value, then apply softmax over only those k values.
  Description: Used for the SOFTMAX_WEIGHT expert-routing variant (gpt-oss), which differs from `topKSoftmax` in that softmax is applied to the pre-selected raw logits rather than to the full probability distribution first.
  Param logits: Raw router logit values, one per expert.
  Param k: Number of top experts to select.
  Param out_ids: Output slice of length k; filled with the indices of selected experts.
  Param out_weights: Output slice of length k; filled with softmax-normalized weights.

- topKSoftmax [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#top-ksoftmax
  Signature: pub fn topKSoftmax(logits: []const f32, k: u32, out_ids: []u32, out_weights: []f32) void
  Summary: Apply softmax over all logits, then select the top-k entries by probability and renormalize.
  Param logits: Raw router logit values, one per expert.
  Param k: Number of top experts to select.
  Param out_ids: Output slice of length k; filled with the indices of selected experts.
  Param out_weights: Output slice of length k; filled with renormalized softmax weights.

- generateWithMetrics [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#generate-with-metrics
  Signature: pub fn generateWithMetrics( engine: *InferenceEngine, prompt_tokens: []const u32, max_tokens: u32, eos_id: u32, allocator: std.mem.Allocator, ) !GenerateResult
  Summary: Run prompt prefill followed by autoregressive decode and return tokens with timing metrics.
  Param engine: Initialized inference engine owning the model weights and KV cache.
  Param prompt_tokens: Tokenized prompt; may be empty for continuation from a prior state.
  Param max_tokens: Upper bound on the number of tokens to generate (not counting prompt).
  Param eos_id: Token id that terminates generation early when sampled.
  Param allocator: Used to allocate the returned `output_tokens` slice; caller must free via `GenerateResult.deinit`.
  Returns: `GenerateResult` with the generated token slice and per-phase timing metrics.

- generate [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-metal/#generate
  Signature: pub fn generate( engine: *InferenceEngine, prompt_tokens: []const u32, max_tokens: u32, eos_id: u32, allocator: std.mem.Allocator, ) ![]u32
  Summary: Run prefill and decode, log throughput, and return only the generated token slice.
  Description: Convenience wrapper around `generateWithMetrics` for callers that do not need the structured `GenerateMetrics` breakdown.
  Param engine: Initialized inference engine owning the model weights and KV cache.
  Param prompt_tokens: Tokenized prompt passed directly to `generateWithMetrics`.
  Param max_tokens: Upper bound on tokens to generate.
  Param eos_id: Token id that terminates generation early when sampled.
  Param allocator: Used to allocate the returned slice; caller is responsible for freeing it.
  Returns: Caller-owned slice of generated token ids (excludes the prompt).

### Module: Forward Zinc Rt
URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-zinc-rt/
Source: src/compute/forward_zinc_rt.zig
Code lines: 9253
Summary: ZINC_RT forward-pass bring-up.
Overview: M1 wires a scalar forward path for the hybrid Qwen MoE+SSM model used by the RDNA migration harness, plus the first AMDGPU-CS-produced token boundary. The old no-layer tail remains as a smoke fallback for unsupported shapes.

- m0_max_decode_tokens_default [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-zinc-rt/#m0-max-decode-tokens-default
  Signature: pub const m0_max_decode_tokens_default: u32 = 8
  Summary: Decode-token budget used by the no-layer smoke tail (`generateNoLayer`) and by benchmarks that want a short, bounded run on the scalar reference path.
  Description: The full M1 forward paths (`generateScalarHybrid`, `generateScalarDense`) pass the caller-supplied `max_tokens` through unchanged and never consult this constant. Override via ZINC_RT_MAX_DECODE_TOKENS.

- Model [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-zinc-rt/#model
  Signature: pub const Model = struct
  Summary: Loaded GGUF model plus all the load-time scratch derived from it.
  Description: Owns the mmap'd file, the resolved per-layer tensor table, the cached F32 dequants of small norm/SSM-side tensors, and the re-quantized weight blobs the decode path streams in place of the larger source-format weights. A `Model` is built once with `load` and consumed by `generate` / `generateWithOptions`; the GPU rings get the same handle so they can read the underlying bytes too.
  - Model.load [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-zinc-rt/#model-load
    Signature: pub fn load(path: []const u8, allocator: std.mem.Allocator) !Model
    Summary: Memory-map a GGUF model file, parse its metadata, and pre-build the load-time caches the scalar decode path relies on (small F32 norm/SSM tensors, Q8_0→Q4_0 and F32→Q8_0 re-quantizations of the heavier per-token weight streams, RoPE inverse-frequency table, attention sinks, SSM conv1d kernels).
    Description: The returned handle must eventually be released with `deinit`. unreadable, the tensors don't match the expected shapes, or the GGUF metadata is malformed.
    Param path: Filesystem path to the GGUF model.
    Param allocator: Owns every secondary allocation reachable from `Model`.
    Returns: A fully-initialised `Model`, or an error if the file is
  - Model.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-zinc-rt/#model-deinit
    Signature: pub fn deinit(self: *Model) void
    Summary: Release every allocation reachable from `Model`: the re-quantized weight blobs, the small-tensor F32 cache, the SSM/RoPE/attention-sink scratch, the GGUF parse state, the mmap, and the file handle.
    Description: Poisons `self`; the handle must not be reused afterwards.
  - Model.validateDecodeGraph [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-zinc-rt/#model-validate-decode-graph
    Signature: pub fn validateDecodeGraph(self: *const Model, allocator: std.mem.Allocator) !DecodeGraphSummary
    Summary: Emit the per-token decode IR for this model's shape and run the validator on it, returning a node/layer count summary the caller can log or assert against.
    Description: Used as an admission gate before a real decode run so a malformed graph fails loud and early instead of corrupting the scalar kernels mid-token. return.
    Param allocator: Used for the throwaway IR graph; released before
    Returns: Summary of the emitted-and-validated decode graph.

- DecodeGraphSummary [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-zinc-rt/#decode-graph-summary
  Signature: pub const DecodeGraphSummary = struct
  Summary: Counts produced by `Model.validateDecodeGraph` — how many IR nodes were emitted, and how the per-layer mix (full attention, SSM, MoE) breaks down.
  Description: Useful for asserting the lowered graph matches the model's expected shape.

- DirectComputeKind [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-zinc-rt/#direct-compute-kind
  Signature: pub const DirectComputeKind = enum
  Summary: Tag identifying which direct-compute shortcut the active tier executed for the current decode step.
  Description: `none` means the scalar host path retired the token; the other variants name the kernel the GPU ring actually ran (a first-element RMSNorm, an argmax, an argmax composed with that RMSNorm, or a row-range dequantized matvec).

- BenchmarkShortcutFlags [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-zinc-rt/#benchmark-shortcut-flags
  Signature: pub const BenchmarkShortcutFlags = struct
  Summary: Flags marking which benchmark-only fast-paths influenced the run.
  Description: The performance suite consults these to decide whether a number is comparable to the reference scalar path or whether a measurement-only shortcut was in effect (top-k forced to zero, LM-head row count capped, decode budget clamped).
  - BenchmarkShortcutFlags.any [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-zinc-rt/#benchmark-shortcut-flags-any
    Signature: pub fn any(self: BenchmarkShortcutFlags) bool
    Summary: True if any benchmark shortcut was applied during the run.

- GenerateResult [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-zinc-rt/#generate-result
  Signature: pub const GenerateResult = struct
  Summary: Output of a `generate` / `generateWithOptions` call: the produced token stream, prefill / decode wall-clock splits, the originally-requested and effective decode budgets, and a set of direct-tier instrumentation counters that report how much of the per-token work was actually retired by the GPU ring versus by the scalar fallback.
  Description: The token slice is allocator-owned and must be released with `deinit`.
  - GenerateResult.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-zinc-rt/#generate-result-deinit
    Signature: pub fn deinit(self: *GenerateResult, allocator: std.mem.Allocator) void
    Summary: Free the produced token slice and poison the handle.
    Param allocator: Same allocator that was passed to `generate`.

- GenerateOptions [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-zinc-rt/#generate-options
  Signature: pub const GenerateOptions = struct
  Summary: Knobs threaded through to `generateWithOptions`.
  Description: Lets callers opt out of the per-token direct-tier admission validation when they only want the scalar reference numbers.

- generate [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-zinc-rt/#generate
  Signature: pub fn generate( model: *const Model, prompt_tokens: []const u32, max_tokens: u32, eos_token_id: u32, allocator: std.mem.Allocator, ) !GenerateResult
  Summary: Run the full ZINC_RT forward pass against `model` with default `GenerateOptions`: prefill the prompt, validate the per-token decode IR, and decode at most `max_tokens` tokens (stopping early on `eos_token_id`).
  Description: Tries the scalar hybrid path, then the scalar dense path, then falls back to a no-layer smoke tail. Equivalent to `generateWithOptions(..., .{})`.
  Param model: Loaded GGUF model.
  Param prompt_tokens: Tokenised prompt; must be non-empty.
  Param max_tokens: Upper bound on tokens to produce after prefill.
  Param eos_token_id: Stop-token id.
  Param allocator: Owns the returned `GenerateResult.tokens`.
  Returns: A `GenerateResult` the caller must release via its `deinit`.

- generateWithOptions [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-zinc-rt/#generate-with-options
  Signature: pub fn generateWithOptions( model: *const Model, prompt_tokens: []const u32, max_tokens: u32, eos_token_id: u32, allocator: std.mem.Allocator, options: GenerateOptions, ) !GenerateResult
  Summary: Full ZINC_RT forward pass with caller-supplied `GenerateOptions`.
  Description: Logs the validated decode-graph summary, then picks among three paths: the scalar hybrid MoE+SSM path (for Qwen 3.6-shaped models whose tensors fully resolve via `canRunScalarHybrid`), the scalar dense attention path (for Gemma 4-shaped models via `canRunScalarDense`), and the no-layer smoke tail (everything else). The hybrid and dense paths consume the GPU ring's direct-compute results; the smoke tail is CPU-only. throwaway decode IR.
  Param model: Loaded GGUF model.
  Param prompt_tokens: Tokenised prompt; must be non-empty.
  Param max_tokens: Upper bound on tokens to produce after prefill.
  Param eos_token_id: Stop-token id.
  Param allocator: Owns the returned `GenerateResult.tokens` and the
  Param options: Per-call configuration; see `GenerateOptions`.
  Returns: A `GenerateResult` the caller must release via its `deinit`.

- initTokenizer [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-zinc-rt/#init-tokenizer
  Signature: pub fn initTokenizer(model: *const Model, allocator: std.mem.Allocator) !Tokenizer
  Summary: Build a `Tokenizer` from `model`'s GGUF vocab metadata.
  Description: Convenience wrapper around `Tokenizer.init` so callers don't have to reach into the `Model`'s parse state.
  Param model: Loaded GGUF model whose vocab table is consulted.
  Param allocator: Owns the resulting tokenizer's vocab and id table.
  Returns: A ready-to-use `Tokenizer`.

- Tokenizer [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-zinc-rt/#tokenizer
  Signature: pub const Tokenizer = struct
  Summary: Minimal longest-match BPE-ish tokenizer that reads the vocab and EOS id straight out of a GGUF file.
  Description: Encodes prompts via the GPT-2 byte-to-unicode mapping and falls back to byte 0 on misses so the scalar M1 forward path always sees a well-formed token stream.
  - Tokenizer.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-zinc-rt/#tokenizer-init
    Signature: pub fn init(gf: *const gguf.GGUFFile, allocator: std.mem.Allocator) !Tokenizer
    Summary: Build a tokenizer by reading `tokenizer.ggml.tokens` and `tokenizer.ggml.eos_token_id` out of `gf`.
    Description: Defaults the EOS id to `2` when the metadata key is missing.
    Param gf: GGUF file whose tokenizer metadata is consulted.
    Param allocator: Owns the vocab slice and the id hash table.
    Returns: A `Tokenizer` ready for `encodePrompt` / `decodeToken`.
  - Tokenizer.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-zinc-rt/#tokenizer-deinit
    Signature: pub fn deinit(self: *Tokenizer) void
    Summary: Release the vocab slice and the id hash table, then poison the handle.
  - Tokenizer.eosId [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-zinc-rt/#tokenizer-eos-id
    Signature: pub fn eosId(self: *const Tokenizer) u32
    Summary: Return the stop token id the caller should pass to `generate`.
  - Tokenizer.encodeGemmaChat [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-zinc-rt/#tokenizer-encode-gemma-chat
    Signature: pub fn encodeGemmaChat(self: *const Tokenizer, user_text: []const u8, allocator: std.mem.Allocator) !?[]u32
    Summary: Wrap the user prompt with Gemma's chat-turn special tokens so the instruction-tuned model has the expected scaffolding.
    Description: Tries the Gemma 4 tokens (`<|turn>` / `<turn|>`) first, then falls back to Gemma 2/3 tokens (`<start_of_turn>` / `<end_of_turn>`). Returns null when neither set is present in the vocab (i.e. the model isn't Gemma-templated).
  - Tokenizer.encodePrompt [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-zinc-rt/#tokenizer-encode-prompt
    Signature: pub fn encodePrompt(self: *const Tokenizer, text: []const u8, allocator: std.mem.Allocator) ![]u32
    Summary: Encode `text` into a token id stream using a longest-match scan over the vocab.
    Description: GPT-2-flavour tokenizers (Qwen) use the byte-to-unicode mapping; SentencePiece-flavour tokenizers (Gemma) substitute spaces with ▁ and pass raw UTF-8 through. Prepends BOS when `add_bos` is set. Unmatched single bytes fall back to token id 0 so the output is always well-formed.
    Param text: Raw UTF-8 prompt bytes.
    Param allocator: Owns the returned token slice.
    Returns: Token ids ready to feed into `generate`.
  - Tokenizer.decodeToken [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward-zinc-rt/#tokenizer-decode-token
    Signature: pub fn decodeToken(self: *const Tokenizer, token_id: u32, buf: []u8) []const u8
    Summary: Render one token id back to its UTF-8 byte form into `buf`.
    Description: For GPT-2-flavour vocabs the GPT-2 byte-to-unicode mapping is reversed; for SentencePiece-flavour vocabs the SPIECE underline (▁, U+2581) is mapped to a plain space and remaining codepoints are copied as-is. Truncates instead of erroring when `buf` is too small; returns an empty slice for out-of-range ids.
    Param token_id: Token id produced by `generate` or `encodePrompt`.
    Param buf: Scratch buffer the decoded bytes are written into.
    Returns: The prefix of `buf` containing the decoded bytes.

### Module: Forward
URL: https://zolotukhin.ai/zinc/docs/zig-api/forward/
Source: src/compute/forward.zig
Code lines: 26736
Summary: Run the inference runtime: decode state, pipeline ownership, and token generation.
Overview: This module ties together model state, compute graphs, dispatch helpers, and greedy token sampling for a single active inference engine.

- DecodeState [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward/#decode-state
  Signature: pub const DecodeState = struct
  Summary: Runtime state for the decode loop.
  - DecodeState.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward/#decode-state-init
    Signature: pub fn init(allocator: std.mem.Allocator) DecodeState
    Summary: Initialize decode state for a fresh generation request.
    Param allocator: Allocator used for the generated token list.
    Returns: A DecodeState positioned at token index zero with an empty output buffer.
  - DecodeState.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward/#decode-state-deinit
    Signature: pub fn deinit(self: *DecodeState) void
    Summary: Release the generated token buffer owned by the decode state.
    Param self: Decode state to tear down in place.
    Note: After this call the state is invalid and should not be reused.

- SamplingParams [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward/#sampling-params
  Signature: pub const SamplingParams = struct
  Summary: Token sampling controls shared by the decode loop and HTTP server.
  - SamplingParams.requiresLogitsReadback [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward/#sampling-params-requires-logits-readback
    Signature: pub fn requiresLogitsReadback(self: @This()) bool
    Summary: Return whether the current sampling settings require CPU-visible logits.
    Description: (i.e. any path that needs more than just the argmax token index).
    Returns: `true` when temperature, top-p, or repetition-penalty are active

- InferenceEngine [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward/#inference-engine
  Signature: pub const InferenceEngine = struct
  Summary: Central inference engine that owns the GPU resources for one active model.
  Description: Holds the loaded model, all Vulkan pipelines and intermediate activation buffers, KV-cache page pool, SSM recurrent state, and per-request profiling counters. One engine instance maps to one GPU device; it is not thread-safe.
  - InferenceEngine.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward/#inference-engine-init
    Signature: pub fn init( model: *Model, instance: *const Instance, gpu_config: GpuConfig, shader_dir: []const u8, allocator: std.mem.Allocator, ) !InferenceEngine
    Summary: Create the runtime objects needed to execute decode-time work on the GPU.
    Param model: Loaded model weights and metadata.
    Param instance: Active Vulkan instance and logical device.
    Param gpu_config: Derived GPU tuning parameters for the selected device.
    Param shader_dir: Directory containing compiled SPIR-V shader binaries.
    Param allocator: Allocator used for graphs, staging state, and temporary setup structures.
    Returns: An initialized inference engine ready to prefill prompts and run decode steps.
    Note: This allocates shared descriptor pools, staging buffers, intermediate activations, and dispatch wrappers up front.
  - InferenceEngine.enableProfiling [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward/#inference-engine-enable-profiling
    Signature: pub fn enableProfiling(self: *InferenceEngine) !void
    Summary: Enable full GPU + CPU profiling.
    Description: The timestamp query pool is created in `init`, so this just flips the runtime flag. Returns an error if pool creation failed.
  - InferenceEngine.enableValidationDiagnostics [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward/#inference-engine-enable-validation-diagnostics
    Signature: pub fn enableValidationDiagnostics(self: *InferenceEngine) void
    Summary: Enable the expensive CPU-vs-GPU validation readbacks used for debugging kernel correctness.
  - InferenceEngine.enableLogitsReadback [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward/#inference-engine-enable-logits-readback
    Signature: pub fn enableLogitsReadback(self: *InferenceEngine) void
    Summary: Preserve full logits on the host for debug dumps and diagnostic inspection.
  - InferenceEngine.recordProfilingSample [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward/#inference-engine-record-profiling-sample
    Signature: pub fn recordProfilingSample(self: *InferenceEngine) void
    Summary: Read back all timestamps for the current token and fold them into request-wide profiling stats.
  - InferenceEngine.decodeStep [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward/#inference-engine-decode-step
    Signature: pub fn decodeStep(self: *InferenceEngine, state: *DecodeState, token_id: u32, collect_output: bool) !void
    Summary: Run a single decode step for one token through all transformer layers.
    Description: embed → [per-layer: norm → QKV → RoPE → KV write → attention → O proj → residual → FFN norm → MoE routing → expert DMMVs → residual] → final norm → LM head → logits diagnostic or GPT-OSS embedding-collection paths.
    Param state: Decode state carrying the current token position and generated token history.
    Param token_id: Vocabulary index of the token to embed and feed forward.
    Param collect_output: When `true`, the engine accumulates layer outputs needed by
    Returns: `error.ContextLengthExceeded` when `state.position` is at capacity.
  - InferenceEngine.prefillBatched [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward/#inference-engine-prefill-batched
    Signature: pub fn prefillBatched(self: *InferenceEngine, state: *DecodeState, prompt_tokens: []const u32) !void
    Summary: Experimental batched prompt prefill for the RDNA/Vulkan backend. Gated by `ZINC_BATCHED_PREFILL=1`. This is the Vulkan analogue of `forward_metal.InferenceEngine.prefillBatched`.
    Description: Routes to `prefillA3bProduction` or `prefillQwen36DenseFfnPrefix` when the model and prompt length match those specialized paths; otherwise falls back to the `canUseBatchedPrefillRdna`-gated batched body or `prefillBatch` (per-token serial path). Set `ZINC_BATCHED_PREFILL=0` to force the serial fallback or `=validate` to run both paths and diff the last-token logits. Intel Arc Gemma uses the chunked batched path by default; Qwen 3.6 A3B uses the specialized layer-major path by default; other Intel models still require `ZINC_INTEL_BATCHED_PREFILL=1` to opt in.
    Param state: Decode state for the current request.
    Param prompt_tokens: Tokenized prompt sequence to prefill.
  - InferenceEngine.prefillBatch [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward/#inference-engine-prefill-batch
    Signature: pub fn prefillBatch(self: *InferenceEngine, state: *DecodeState, prompt_tokens: []const u32) !void
    Summary: Process all prompt tokens sequentially (one token per GPU submission) to populate KV cache and SSM state before the first decode step.
    Description: an active KV-page allocation for continuation prefill.
    Param state: Decode state; must start at position 0 for a fresh request or have
    Param prompt_tokens: Tokenized input sequence to prefill. No-op when empty.
    Note: This is the per-token serial path. For the experimental batched variant see `prefillBatched`.
  - InferenceEngine.sampleGreedy [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward/#inference-engine-sample-greedy
    Signature: pub fn sampleGreedy(self: *const InferenceEngine) u32
    Summary: Sample a token greedily.
    Description: Uses GPU argmax when available, otherwise falls back to CPU scan.
    Returns: The vocabulary index of the highest-logit token.
  - InferenceEngine.sample [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward/#inference-engine-sample
    Signature: pub fn sample(self: *const InferenceEngine, state: *const DecodeState, params: SamplingParams, random: std.Random) u32
    Summary: Sample the next token using greedy argmax or stochastic sampling depending on `params`.
    Description: Delegates to `sampleGreedy` when no logit readback is needed; otherwise reads staged logits from the host and applies temperature, top-p, top-k, and repetition penalty.
    Param state: Decode state supplying the generated-token history for repetition penalty.
    Param params: Sampling hyper-parameters controlling temperature and nucleus filtering.
    Param random: Random source for stochastic sampling; unused on the greedy path.
    Returns: The sampled vocabulary token index.
  - InferenceEngine.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/forward/#inference-engine-deinit
    Signature: pub fn deinit(self: *InferenceEngine) void
    Summary: Release GPU buffers, graphs, command objects, and dispatch helpers owned by the engine.

- generate [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/forward/#generate
  Signature: pub fn generate( engine: *InferenceEngine, prompt_tokens: []const u32, max_tokens: u32, eos_token_id: u32, allocator: std.mem.Allocator, ) ![]u32
  Summary: Run single-request inference: prefill the prompt, decode greedily, and return generated token IDs.
  Param engine: Initialized inference engine.
  Param prompt_tokens: Tokenized prompt that seeds the prefill pass.
  Param max_tokens: Maximum number of decode tokens to emit after prefill.
  Param allocator: Allocator used for transient decode state and the returned token slice.
  Returns: A heap-allocated slice containing only the generated continuation tokens.
  Note: Generation stops early when the sampled token equals `eos_token_id`.

### Module: Interface
URL: https://zolotukhin.ai/zinc/docs/zig-api/interface/
Source: src/gpu/interface.zig
Code lines: 47
Summary: GPU backend abstraction — comptime-resolved, zero runtime overhead.
Overview: macOS → Metal. Linux → Vulkan by default, or CUDA with `-Dbackend=cuda` (NVIDIA / WSL2, where Vulkan is CPU-only). See docs/cuda-backend.md.

- is_metal [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/interface/#is-metal
  Signature: pub const is_metal = builtin.os.tag == .macos
  Summary: True when compiling for macOS (Metal backend).

- is_cuda [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/interface/#is-cuda
  Signature: pub const is_cuda = builtin.os.tag == .linux and std.mem.eql(u8, build_options.backend, "cuda")
  Summary: True when compiling for Linux with `-Dbackend=cuda` (NVIDIA / WSL2).

- is_vulkan [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/interface/#is-vulkan
  Signature: pub const is_vulkan = builtin.os.tag == .linux and !is_cuda
  Summary: True when compiling for Linux with the Vulkan backend (the Linux default).

- backend [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/interface/#backend
  Signature: pub const backend = if (is_metal) @import("../metal/device.zig") else if (is_cuda) @import("../cuda/device.zig") else @import("../vulkan/instance.zig")
  Summary: Platform-specific GPU device module (Metal / CUDA / Vulkan).

- vk [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/interface/#vk
  Signature: pub const vk = if (is_vulkan) @import("../vulkan/vk.zig") else struct}
  Summary: Vulkan C bindings (empty struct off-Vulkan).

### Module: Memory Plan
URL: https://zolotukhin.ai/zinc/docs/zig-api/memory-plan/
Source: src/gpu/memory_plan.zig
Code lines: 290
Summary: Shared runtime memory accounting helpers for Vulkan and Metal backends.
Overview: The helpers in this module turn model dimensions plus backend-specific runtime characteristics into a comparable memory budget so diagnostics, server load policy, and inference engines size context and KV consistently.

- RuntimeMemoryProfile [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/memory-plan/#runtime-memory-profile
  Signature: pub const RuntimeMemoryProfile = struct
  Summary: Backend-agnostic breakdown of runtime memory as: - fixed bytes that do not scale with context length - bytes that scale linearly per token
  - RuntimeMemoryProfile.deviceLocalContextBytes [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/memory-plan/#runtime-memory-profile-device-local-context-bytes
    Signature: pub fn deviceLocalContextBytes(self: @This(), context_tokens: u32) u64
    Summary: Return device-local bytes consumed by context-scaled runtime state.
  - RuntimeMemoryProfile.hostVisibleContextBytes [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/memory-plan/#runtime-memory-profile-host-visible-context-bytes
    Signature: pub fn hostVisibleContextBytes(self: @This(), context_tokens: u32) u64
    Summary: Return host-visible bytes consumed by context-scaled runtime state.
  - RuntimeMemoryProfile.runtimeDeviceLocalBytes [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/memory-plan/#runtime-memory-profile-runtime-device-local-bytes
    Signature: pub fn runtimeDeviceLocalBytes(self: @This(), context_tokens: u32) u64
    Summary: Return total device-local runtime bytes for the requested context length.
  - RuntimeMemoryProfile.runtimeHostVisibleBytes [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/memory-plan/#runtime-memory-profile-runtime-host-visible-bytes
    Signature: pub fn runtimeHostVisibleBytes(self: @This(), context_tokens: u32) u64
    Summary: Return total host-visible runtime bytes for the requested context length.
  - RuntimeMemoryProfile.runtimeUnifiedBytes [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/memory-plan/#runtime-memory-profile-runtime-unified-bytes
    Signature: pub fn runtimeUnifiedBytes(self: @This(), context_tokens: u32) u64
    Summary: Return total unified-memory runtime bytes for the requested context length.
  - RuntimeMemoryProfile.totalDeviceLocalBytes [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/memory-plan/#runtime-memory-profile-total-device-local-bytes
    Signature: pub fn totalDeviceLocalBytes(self: @This(), weights_bytes: u64, context_tokens: u32) u64
    Summary: Return weights plus device-local runtime bytes for the requested context length.
  - RuntimeMemoryProfile.totalUnifiedBytes [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/memory-plan/#runtime-memory-profile-total-unified-bytes
    Signature: pub fn totalUnifiedBytes(self: @This(), weights_bytes: u64, context_tokens: u32) u64
    Summary: Return weights plus unified runtime bytes for the requested context length.
  - RuntimeMemoryProfile.maxContextTokensForDeviceLocalBudget [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/memory-plan/#runtime-memory-profile-max-context-tokens-for-device-local-budget
    Signature: pub fn maxContextTokensForDeviceLocalBudget( self: @This(), weights_bytes: u64, budget_bytes: u64, ceiling: u32, ) u32
    Summary: Return the largest context that fits within a device-local memory budget.
    Param weights_bytes: Size of model weights already placed on the device.
    Param budget_bytes: Total device-local memory budget available.
    Param ceiling: Architectural context-length ceiling (e.g. from GGUF).
    Returns: Token count clamped to both the budget and `ceiling`.
  - RuntimeMemoryProfile.maxContextTokensForUnifiedBudget [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/memory-plan/#runtime-memory-profile-max-context-tokens-for-unified-budget
    Signature: pub fn maxContextTokensForUnifiedBudget( self: @This(), weights_bytes: u64, budget_bytes: u64, ceiling: u32, ) u32
    Summary: Return the largest context that fits within a unified-memory budget.
    Description: Combines device-local and host-visible costs (both fixed and per-token) when computing available room, suitable for backends with a single unified address space such as Metal.
    Param weights_bytes: Size of model weights counted against the budget.
    Param budget_bytes: Total unified-memory budget available.
    Param ceiling: Architectural context-length ceiling.
    Returns: Token count clamped to both the budget and `ceiling`.

- effectiveContextCeiling [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/memory-plan/#effective-context-ceiling
  Signature: pub fn effectiveContextCeiling(config: ModelConfig, requested_context_length: ?u32) u32
  Summary: Clamp the requested context length against the model's declared context limit.
  Param config: Model configuration supplying `context_length` as the hard ceiling.
  Param requested_context_length: Optional caller-supplied cap; `null` means use the model ceiling.
  Returns: The smaller of `config.context_length` and the requested cap.

- applyRequestedContextLimit [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/memory-plan/#apply-requested-context-limit
  Signature: pub fn applyRequestedContextLimit(config: *ModelConfig, requested_context_length: ?u32) void
  Summary: Apply the requested context cap directly to a mutable model config.
  Description: Mutates `config.context_length` in place so that downstream code reading the config sees the clamped value without needing to carry a separate cap.
  Param config: Config to mutate; `context_length` is lowered if necessary.
  Param requested_context_length: Optional cap; ignored when larger than the current ceiling.

- requestedContextTokens [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/memory-plan/#requested-context-tokens
  Signature: pub fn requestedContextTokens(config: ModelConfig, requested_context_length: ?u32, backend_cap: u32) u32
  Summary: Return the runtime context target after applying both model and backend caps.
  Description: Applies the model ceiling first (`effectiveContextCeiling`), then further clamps to the backend's hardware-derived limit.
  Param config: Model configuration providing the architectural ceiling.
  Param requested_context_length: Optional user-supplied context length cap.
  Param backend_cap: Hardware or driver limit reported by the backend.
  Returns: Final context length clamped to all three bounds.

- remainingContextTokens [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/memory-plan/#remaining-context-tokens
  Signature: pub fn remainingContextTokens(used_context_tokens: u32, context_capacity_tokens: u32) u32
  Summary: Return how many context slots remain available for a request.
  Description: Uses saturating subtraction so the result is 0 rather than wrapping when `used_context_tokens` exceeds the capacity.
  Param used_context_tokens: Tokens already committed in the current context window.
  Param context_capacity_tokens: Total context window size in tokens.
  Returns: Remaining free slots, clamped to 0 on overflow.

- clampedCompletionTokens [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/memory-plan/#clamped-completion-tokens
  Signature: pub fn clampedCompletionTokens( used_context_tokens: u32, requested_completion_tokens: u32, context_capacity_tokens: u32, ) u32
  Summary: Clamp requested completion tokens against the remaining context budget.
  Param used_context_tokens: Tokens already in the context window.
  Param requested_completion_tokens: Caller-requested number of new tokens to generate.
  Param context_capacity_tokens: Total context capacity.
  Returns: Actual completion quota, never exceeding the remaining room.

- requestContextTarget [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/memory-plan/#request-context-target
  Signature: pub fn requestContextTarget( used_context_tokens: u32, requested_completion_tokens: u32, context_capacity_tokens: u32, ) u32
  Summary: Return the total context target needed for prompt plus completion work.
  Description: Adds the clamped completion quota to the tokens already used, then caps the result at `context_capacity_tokens` to prevent over-allocation.
  Param used_context_tokens: Tokens already occupying the context window.
  Param requested_completion_tokens: Tokens the caller wants to generate.
  Param context_capacity_tokens: Hard upper bound on the context window size.
  Returns: Total tokens to allocate, bounded by capacity.

- RequestBudget [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/memory-plan/#request-budget
  Signature: pub const RequestBudget = struct
  Summary: Completion-token budget and resulting context target for one request.

- requestBudget [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/memory-plan/#request-budget
  Signature: pub fn requestBudget( used_context_tokens: u32, requested_completion_tokens: u32, context_capacity_tokens: u32, ) RequestBudget
  Summary: Compute the clamped completion budget and resulting context target for one request.
  Description: Combines `clampedCompletionTokens` and `requestContextTarget` into a single call so callers get both values in one pass. total context window size to allocate for this request.
  Param used_context_tokens: Tokens already committed in the context window.
  Param requested_completion_tokens: Tokens the caller wants to generate.
  Param context_capacity_tokens: Total context capacity.
  Returns: `RequestBudget` with the actual completion quota and the

- profile [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/memory-plan/#profile
  Signature: pub fn profile(config: ModelConfig) RuntimeMemoryProfile
  Summary: Build the backend-agnostic runtime memory profile for a normalized model config.
  Description: Computes all fixed and per-token memory costs from model dimensions, including attention buffers, FFN/MoE scratch buffers, SSM convolution and state buffers, and KV-cache scaling. The returned profile does not include model weights.
  Param config: Model configuration with dimensions, expert counts, and SSM parameters.
  Returns: `RuntimeMemoryProfile` capturing fixed overhead and per-token KV cost.

- auto_context_floor_tokens [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/memory-plan/#auto-context-floor-tokens
  Signature: pub const auto_context_floor_tokens: u32 = 4096
  Summary: vLLM-style floor for auto-sized context: never fall below this even if the memory math suggests less — the server would otherwise become unusable.

- autoContextTokensForDeviceBudget [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/memory-plan/#auto-context-tokens-for-device-budget
  Signature: pub fn autoContextTokensForDeviceBudget( profile_value: RuntimeMemoryProfile, weights_bytes: u64, device_budget_bytes: u64, architectural_ceiling: u32, ) u32
  Summary: Derive a context length from an available device-memory budget.
  Description: Analogous to vLLM's `determine_available_memory` → `get_num_blocks` flow, adapted for a contiguous (non-paged) KV cache: 1. Reserve a utilization fraction of the device budget. 2. Subtract model weights and fixed runtime overhead. 3. Divide the leftover by the per-token KV cost. 4. Clamp to the architectural ceiling from GGUF and floor at 4096 so tiny or very-tight budgets still produce a usable server.

### Module: Process Lock
URL: https://zolotukhin.ai/zinc/docs/zig-api/process-lock/
Source: src/gpu/process_lock.zig
Code lines: 48
Summary: Cross-process GPU reservation lock keyed by backend and selected device.
Overview: ZINC uses a filesystem lock to stop multiple inference processes from loading different models onto the same physical GPU at once, which would otherwise produce confusing OOM failures and unstable benchmark results.

- Backend [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/process-lock/#backend
  Signature: pub const Backend = enum
  Summary: Backend identifier encoded into the shared GPU lockfile name.

- ProcessLock [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/process-lock/#process-lock
  Signature: pub const ProcessLock = struct
  Summary: Cross-process lock handle that reserves one backend/device pair.
  - ProcessLock.isHeld [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/process-lock/#process-lock-is-held
    Signature: pub fn isHeld(self: *const ProcessLock) bool
    Summary: Return whether the lock currently owns an open lockfile handle.
  - ProcessLock.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/process-lock/#process-lock-deinit
    Signature: pub fn deinit(self: *ProcessLock) void
    Summary: Release the held lockfile handle, if any.

- AcquireError [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/process-lock/#acquire-error
  Signature: pub const AcquireError = std.fs.File.OpenError || error{
  Summary: Errors returned while acquiring a backend/device GPU reservation lock.

- lockPath [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/process-lock/#lock-path
  Signature: pub fn lockPath(buffer: []u8, backend: Backend, device_index: u32) error{LockPathTooLong}![]const u8
  Summary: Format the lockfile path for a backend/device pair into the caller-supplied buffer.
  Param buffer: Destination slice for the formatted path; must be large enough to hold the formatted path.
  Param backend: The GPU backend whose tag name is embedded in the path.
  Param device_index: Zero-based device index embedded in the path.
  Returns: A slice into `buffer` holding the formatted path string, e.g. `/tmp/zinc-gpu-vulkan-0.lock`.
  Note: Returns `error.LockPathTooLong` if `buffer` is too small to hold the formatted path.

- acquire [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/process-lock/#acquire
  Signature: pub fn acquire(backend: Backend, device_index: u32) AcquireError!ProcessLock
  Summary: Acquire the cross-process GPU reservation lock for a backend/device pair.
  Description: Opens the lockfile in non-blocking exclusive mode so that a second process attempting to claim the same GPU immediately receives `error.GpuAlreadyReserved` rather than blocking indefinitely.
  Param backend: The GPU backend to reserve.
  Param device_index: Zero-based index of the device to reserve within that backend.
  Returns: A `ProcessLock` holding the open lockfile handle; caller must call `deinit` to release.
  Note: Returns `error.GpuAlreadyReserved` if another process already holds the lock.

### Module: Batching
URL: https://zolotukhin.ai/zinc/docs/zig-api/batching/
Source: src/zinc_rt/batching.zig
Code lines: 376
Summary: Tenant-aware batch planning for ZINC_RT.
Overview: This module owns admission, quotas, and prefill/decode batch selection. It is intentionally independent of the current host-assisted `forward_zinc_rt` execution path so it can be validated before the M3 continuous-batching executor consumes it.

- TenantId [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/batching/#tenant-id
  Signature: pub const TenantId = u32
  Summary: Stable tenant identifier supplied by the API/server layer.

- RequestId [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/batching/#request-id
  Signature: pub const RequestId = u64
  Summary: Monotonic request identifier assigned at admission.

- TenantLimits [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/batching/#tenant-limits
  Signature: pub const TenantLimits = struct
  Summary: Per-tenant admission and scheduling limits.

- RequestConfig [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/batching/#request-config
  Signature: pub const RequestConfig = struct
  Summary: Request metadata needed by the ZINC_RT batch planner.

- RequestState [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/batching/#request-state
  Signature: pub const RequestState = enum
  Summary: Lifecycle tracked by the ZINC_RT batch planner.

- Slot [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/batching/#slot
  Signature: pub const Slot = struct
  Summary: One request slot in the multitenant planner.
  - Slot.promptRemaining [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/batching/#slot-prompt-remaining
    Signature: pub fn promptRemaining(self: Slot) u32
    Summary: Remaining prompt tokens.
  - Slot.decodeDone [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/batching/#slot-decode-done
    Signature: pub fn decodeDone(self: Slot) bool
    Summary: Whether decode has reached the configured maximum.

- BatchKind [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/batching/#batch-kind
  Signature: pub const BatchKind = enum
  Summary: Type of work represented by a batch entry.

- BatchEntry [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/batching/#batch-entry
  Signature: pub const BatchEntry = struct
  Summary: One request inside a selected prefill or decode batch.

- BatchScheduler [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/batching/#batch-scheduler
  Signature: pub const BatchScheduler = struct
  Summary: Fixed-capacity multitenant scheduler for ZINC_RT prefill/decode batches.
  - BatchScheduler.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/batching/#batch-scheduler-init
    Signature: pub fn init(allocator: std.mem.Allocator, max_slots: u32, max_tenants: u32) !BatchScheduler
    Summary: Initialize a fixed-capacity scheduler.
    Param allocator: Allocator for slot and tenant arrays.
    Param max_slots: Maximum live requests across all tenants.
    Param max_tenants: Maximum registered tenants.
  - BatchScheduler.registerTenant [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/batching/#batch-scheduler-register-tenant
    Signature: pub fn registerTenant(self: *BatchScheduler, tenant_id: TenantId, limits: TenantLimits) !void
    Summary: Register or update limits for a tenant.
    Param self: Scheduler to mutate.
    Param tenant_id: Tenant identifier.
    Param limits: New tenant limits.
  - BatchScheduler.submit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/batching/#batch-scheduler-submit
    Signature: pub fn submit(self: *BatchScheduler, config: RequestConfig) !u32
    Summary: Submit a request into the first free slot.
    Returns: Assigned slot ID.
  - BatchScheduler.selectPrefillBatch [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/batching/#batch-scheduler-select-prefill-batch
    Signature: pub fn selectPrefillBatch(self: *BatchScheduler, out: []BatchEntry, max_prompt_tokens: u32) []BatchEntry
    Summary: Select queued/prefilling requests for prompt prefill.
    Param out: Caller-owned scratch for entries.
    Param max_prompt_tokens: Total prompt-token budget for this batch.
    Returns: A slice of `out` with selected prefill entries.
  - BatchScheduler.advancePrefill [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/batching/#batch-scheduler-advance-prefill
    Signature: pub fn advancePrefill(self: *BatchScheduler, slot_id: u32, tokens: u32) !void
    Summary: Account for completed prompt work.
    Param slot_id: Slot that consumed prompt tokens.
    Param tokens: Number of prompt tokens consumed.
  - BatchScheduler.selectDecodeBatch [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/batching/#batch-scheduler-select-decode-batch
    Signature: pub fn selectDecodeBatch(self: *BatchScheduler, out: []BatchEntry, max_slots: u32) []BatchEntry
    Summary: Select active decode requests fairly across slots and tenant limits.
    Param out: Caller-owned scratch for entries.
    Param max_slots: Maximum entries to select.
    Returns: A slice of `out` with selected decode entries.
  - BatchScheduler.recordDecodeToken [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/batching/#batch-scheduler-record-decode-token
    Signature: pub fn recordDecodeToken(self: *BatchScheduler, slot_id: u32) !void
    Summary: Account for one generated decode token.
    Param slot_id: Slot that emitted a token.
  - BatchScheduler.cancel [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/batching/#batch-scheduler-cancel
    Signature: pub fn cancel(self: *BatchScheduler, slot_id: u32) !void
    Summary: Mark a request as cancelled.
  - BatchScheduler.release [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/batching/#batch-scheduler-release
    Signature: pub fn release(self: *BatchScheduler, slot_id: u32) void
    Summary: Release a completed or cancelled slot.
  - BatchScheduler.activeCount [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/batching/#batch-scheduler-active-count
    Signature: pub fn activeCount(self: *const BatchScheduler) u32
    Summary: Number of occupied request slots.
  - BatchScheduler.tenantActiveCount [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/batching/#batch-scheduler-tenant-active-count
    Signature: pub fn tenantActiveCount(self: *const BatchScheduler, tenant_id: TenantId) u32
    Summary: Number of live requests owned by `tenant_id`.
  - BatchScheduler.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/batching/#batch-scheduler-deinit
    Signature: pub fn deinit(self: *BatchScheduler) void
    Summary: Free all planner storage.

### Module: Engine
URL: https://zolotukhin.ai/zinc/docs/zig-api/engine/
Source: src/zinc_rt/engine.zig
Code lines: 100
Summary: ZINC_RT — the ZINC Runtime.
Overview: Owns tier selection and the top-level runtime handle used by future IR emitters and ring backends.

- Tier [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/engine/#tier
  Signature: pub const Tier = enum
  Summary: Execution tier the engine will dispatch through.
  Description: `t1_pm4` and `t2_umq` are the two direct AMDGPU paths; `t_cpu` is the reference scalar fallback; `t_metal`, `t_intel`, and `t_cuda` are reserved for the corresponding native backends.

- Options [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/engine/#options
  Signature: pub const Options = struct
  Summary: Caller-supplied configuration for `Engine.init`.
  Description: Currently just the desired tier; future fields (worker counts, ring depths, telemetry hooks) live here.

- Capabilities [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/engine/#capabilities
  Signature: pub const Capabilities = struct
  Summary: Runtime capability bits surfaced to harnesses and server integration code.
  Description: The batch planner is present, but continuous batched model execution is not wired into `forward_zinc_rt` yet.

- supports_multitenant_batch_planning [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/engine/#supports-multitenant-batch-planning
  Signature: pub const supports_multitenant_batch_planning = true
  Summary: True when ZINC_RT can plan multitenant batches.

- supports_multitenant_batched_execution [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/engine/#supports-multitenant-batched-execution
  Signature: pub const supports_multitenant_batched_execution = false
  Summary: True only when ZINC_RT can execute multiple tenants in one continuous inference loop.
  Description: This remains false until M3 wires the planner into `forward_zinc_rt` and the server runtime.

- Engine [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/engine/#engine
  Signature: pub const Engine = struct
  Summary: Top-level runtime handle.
  Description: Owns the allocator the engine was built with and the selected tier; future revisions will also own the ring backend.
  - Engine.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/engine/#engine-init
    Signature: pub fn init(allocator: std.mem.Allocator, options: Options) !Engine
    Summary: Construct an engine pinned to the requested tier.
    Param allocator: Allocator used for any engine-owned state.
    Param options: Configuration block; `options.tier` selects the backend.
    Returns: A ready-to-use `Engine`.
  - Engine.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/engine/#engine-deinit
    Signature: pub fn deinit(self: *Engine) void
    Summary: Release any engine-owned state and poison the handle.
    Description: Safe to call once per successful `init`.
  - Engine.capabilities [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/engine/#engine-capabilities
    Signature: pub fn capabilities(self: *const Engine) Capabilities
    Summary: Return static runtime capability bits for the selected build.

- parseTier [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/engine/#parse-tier
  Signature: pub fn parseTier(value: []const u8) !Tier
  Summary: Parse a textual tier identifier (e.g.
  Description: from `ZINC_RT_TIER` or a CLI flag) into a `Tier`. Accepts both short (`t1`, `t2`) and canonical (`t1_pm4`, `t2_umq`) names; `auto` defers to `autoTier`. not a recognised name.
  Param value: String to parse.
  Returns: The selected `Tier`, or `error.UnknownZincRtTier` if `value` is

- tierFromEnv [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/engine/#tier-from-env
  Signature: pub fn tierFromEnv() !Tier
  Summary: Read `ZINC_RT_TIER` and parse it, falling back to `autoTier` when unset.
  Returns: The selected `Tier`, or a parse error from `parseTier`.

- autoTier [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/engine/#auto-tier
  Signature: pub fn autoTier() Tier
  Summary: Probe the host for direct-execution paths and return the best available tier.
  Description: Tries T2 UMQ first (the blessed AMDGPU user-queue path), falls back to T1 PM4 over `/dev/kfd` when UMQ admission is refused, and finally to the scalar CPU reference. so T2 admission usually fails and we end up on T1 PM4.
  Returns: The best tier the current host can run today.
  Note: On the bench node the amdgpu firmware rejects compute user queues,

### Module: Fast Pool
URL: https://zolotukhin.ai/zinc/docs/zig-api/fast-pool/
Source: src/zinc_rt/fast_pool.zig
Code lines: 150
Summary: Low-overhead worker pool for the T-CPU decode matvec fan-out.
Overview: Replaces std.Thread.Pool's spawnWg/waitAndWork pattern for the matvec hot path. Each dispatch posts up to N typed tasks to per-worker atomic slots and spins on a per-slot done-sequence — no heap allocation, no mutex, no condvar. Workers are persistent and spin (with brief yields) between dispatches; total CPU footprint is bounded by `n_workers` cores.
Overview: Why bother: the Qwen3.6-MoE+SSM decode dispatches ~200 matvec/fan-out barriers per token through std.Thread.Pool. Each spawnWg does a heap allocation on the global smp_allocator (closure container), takes the pool mutex twice, and signals a condvar; each waitAndWork takes the mutex and waits on a ResetEvent futex. The atomic-only path here is orders of magnitude cheaper per barrier (~tens of ns vs ~µs).
Overview: API: build a small `Task` array, call `dispatchAndRun(&tasks)`. The caller runs `tasks[0]` on the main thread; `tasks[1..n]` are posted to workers 0..n-1. Returns when all tasks have completed.

- max_workers [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/fast-pool/#max-workers
  Signature: pub const max_workers: usize = 16
  Summary: Upper bound on worker threads supported by a single `FastPool`.
  Description: The slot table is sized to this constant so dispatches stay branch-free and cache-friendly; this matches the decode matvec scheduler's current maximum so high-core hosts do not silently fall back to std.Thread.Pool.

- Task [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/fast-pool/#task
  Signature: pub const Task = struct
  Summary: Single unit of work posted into the pool.
  Description: `fn_` is invoked with `ctx` on either the calling thread (task 0) or a worker thread (tasks 1..). The caller owns the storage `ctx` points at and must keep it alive until `dispatchAndRun` returns.

- FastPool [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/fast-pool/#fast-pool
  Signature: pub const FastPool = struct
  Summary: Persistent worker pool that fans matvec barriers out across N threads.
  Description: Slots are cache-line aligned and communicated via release/acquire atomics; see the module doc for the rationale and benchmark numbers.
  - FastPool.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/fast-pool/#fast-pool-init
    Signature: pub fn init(self: *Self, allocator: std.mem.Allocator, n_workers: usize) !void
    Summary: Spawn `n_workers` persistent worker threads bound to this pool.
    Description: Initializes the slot table, then launches each worker on `workerMain`. the stack. or a spawn error from `std.Thread.spawn`.
    Param self: Pool storage; written in place so callers can keep it on
    Param allocator: Used for the `threads` array only.
    Param n_workers: Worker thread count; must be in `1..=max_workers`.
    Returns: `error.InvalidWorkerCount` when `n_workers` is out of range,
  - FastPool.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/fast-pool/#fast-pool-deinit
    Signature: pub fn deinit(self: *Self) void
    Summary: Signal shutdown, wake every worker, join all threads, and free state.
    Description: Bumps each slot's `seq` after raising the shutdown flag so workers observing a spin-loop step out and exit promptly.
  - FastPool.dispatchAndRun [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/fast-pool/#fast-pool-dispatch-and-run
    Signature: pub fn dispatchAndRun(self: *Self, tasks: []const Task) void
    Summary: Post `tasks[1..]` to worker slots and run `tasks[0]` on the calling thread.
    Description: Spins on each worker's done-sequence until all tasks have completed, then returns. `tasks[1..n]` are posted to workers 0..n-1 via atomic slot writes. assert, not a returned error. Passing an empty slice is a no-op.
    Param tasks: Slice of tasks to execute. `tasks[0]` runs on the caller;
    Note: `tasks.len` must be `<= n_workers + 1`; the assertion is a hard
  - FastPool.executorCount [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/fast-pool/#fast-pool-executor-count
    Signature: pub fn executorCount(self: *const Self) usize
    Summary: Return the total number of execution contexts available: worker threads plus the calling thread.
    Description: Use this value to size task arrays passed to `dispatchAndRun`.
    Returns: `n_workers + 1`.

### Module: Dequant
URL: https://zolotukhin.ai/zinc/docs/zig-api/dequant/
Source: src/zinc_rt/isa/cpu_zig/dequant.zig
Code lines: 1443
Summary: Shared scalar GGML dequantization helpers for T-CPU kernels.
Overview: These helpers intentionally mirror the Vulkan backend's CPU diagnostic dequantization so M0 can compare host-side ZINC_RT ops against it.

- row [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dequant/#row
  Signature: pub fn row(raw_data: []const u8, row_index: u32, cols: u32, tensor_type: GGMLType, output: []f32) !void
  Summary: Dequantize one row of a GGML tensor into f32 lanes.
  Description: Dispatches on `tensor_type` and writes the first `cols` entries of `output`. Supports the formats used by ZINC weights today: `.f32`, `.f16`, `.bf16`, `.q8_0`, `.q4_0`, `.q5_1`, `.q4_k`, `.q5_k`, `.q6_k`, and `.mxfp4`. their block size (32 for q4_0/q5_1/q8_0/mxfp4, 256 for q4_k/q5_k/q6_k). `error.InputTooSmall` when the row would overrun `raw_data`, `error.UnsupportedShape` on bad alignment, or `error.UnsupportedTensorType` for formats not handled here.
  Param raw_data: Raw tensor bytes for the full matrix.
  Param row_index: Zero-based row to materialize.
  Param cols: Number of columns per row; quantized formats require this to be a multiple of
  Param tensor_type: GGML quantization tag selecting the decode path.
  Param output: Destination slice; must be at least `cols` long.
  Returns: `error.OutputTooSmall` when `output.len < cols`, `error.EmptyInput` when `cols == 0`,

- dotRow [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dequant/#dot-row
  Signature: pub fn dotRow( raw_data: []const u8, row_index: u32, cols: u32, tensor_type: GGMLType, input: []const f32, scratch: []f32, ) !f32
  Summary: Dot one quantized row against an f32 input vector, dispatching on tensor type.
  Description: Hot formats (`f32`, `f16`, `bf16`, `q4_0`, `q8_0`, `q4_k`, `q5_k`, `q6_k`) take a fused vectorized path that streams weights and folds the dequant scales into the FMAs. Every other format falls back to dequantizing into `scratch` first and then dotting.
  Param raw_data: Raw tensor bytes for the full matrix.
  Param row_index: Zero-based row to dot.
  Param cols: Number of columns per row; subject to the same block-alignment constraints as `row`.
  Param tensor_type: GGML quantization tag selecting the decode path.
  Param input: f32 input vector of length `>= cols`.
  Param scratch: Caller-owned scratch of length `>= cols`; only consumed on the fallback path.
  Returns: The f32 dot product, or an error matching `row`'s shape and size diagnostics.

- dotF32Row [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dequant/#dot-f32-row
  Signature: pub fn dotF32Row(raw_data: []const u8, row_index: u32, cols: u32, input: []const f32) !f32
  Summary: Dot one f32-packed row against `input` using a 16-wide AVX-512-friendly inner loop.
  Description: Uses four independent accumulators driven by a 4-way unroll so the FP-add chain stays short.
  Param raw_data: Raw f32 row-major tensor bytes.
  Param row_index: Zero-based row to dot.
  Param cols: Number of f32 columns in the row.
  Param input: f32 input vector of length `>= cols`.
  Returns: The f32 dot product, or `error.InputTooSmall` when `input` or `raw_data` is shorter than expected.

- dotF16Row [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dequant/#dot-f16-row
  Signature: pub fn dotF16Row(raw_data: []const u8, row_index: u32, cols: u32, input: []const f32) !f32
  Summary: Dot one f16-packed row against an f32 input vector, promoting each weight to f32 on the fly.
  Param raw_data: Raw f16 row-major tensor bytes.
  Param row_index: Zero-based row to dot.
  Param cols: Number of f16 columns in the row.
  Param input: f32 input vector of length `>= cols`.
  Returns: The f32 dot product, or `error.InputTooSmall` when the input or row bytes are too short.

- dotBf16Row [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dequant/#dot-bf16-row
  Signature: pub fn dotBf16Row(raw_data: []const u8, row_index: u32, cols: u32, input: []const f32) !f32
  Summary: Dot one bf16-packed row against an f32 input vector by zero-extending each weight into f32.
  Param raw_data: Raw bf16 row-major tensor bytes.
  Param row_index: Zero-based row to dot.
  Param cols: Number of bf16 columns in the row.
  Param input: f32 input vector of length `>= cols`.
  Returns: The f32 dot product, or `error.InputTooSmall` when the input or row bytes are too short.

- dotQ8_0Row [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dequant/#dot-q8-0-row
  Signature: pub fn dotQ8_0Row(raw_data: []const u8, row_index: u32, cols: u32, input: []const f32) !f32
  Summary: Dot one Q8_0-packed row against an f32 input vector.
  Description: Q8_0 stores 32 signed-int8 weights per block with one f16 scale; this entry point validates block alignment and bounds, then delegates to the unchecked vectorized inner loop.
  Param raw_data: Raw Q8_0 tensor bytes (34 bytes per 32-element block).
  Param row_index: Zero-based row to dot.
  Param cols: Number of columns; must be a multiple of 32.
  Param input: f32 input vector of length `>= cols`.
  Returns: The f32 dot product, or `error.UnsupportedShape` / `error.InputTooSmall` on misuse.

- dotQ4_0Row [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dequant/#dot-q4-0-row
  Signature: pub fn dotQ4_0Row(raw_data: []const u8, row_index: u32, cols: u32, input: []const f32) !f32
  Summary: Dot one Q4_0-packed row against an f32 input vector.
  Description: Q4_0 stores 32 nibble weights with a `-8` bias per block plus an f16 scale; this entry point validates block alignment and bounds, then delegates to the unchecked vectorized inner loop.
  Param raw_data: Raw Q4_0 tensor bytes (18 bytes per 32-element block).
  Param row_index: Zero-based row to dot.
  Param cols: Number of columns; must be a multiple of 32.
  Param input: f32 input vector of length `>= cols`.
  Returns: The f32 dot product, or `error.UnsupportedShape` / `error.InputTooSmall` on misuse.

- quantizeRowToQ4_0 [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dequant/#quantize-row-to-q4-0
  Signature: pub fn quantizeRowToQ4_0(src: []const f32, dst: []u8) void
  Summary: Quantize one row of f32 weights into the GGML `Q4_0` block layout.
  Description: Each 32-element block is stored as one f16 scale followed by 16 packed nibble pairs (low nibble = first weight, high nibble = second weight), where each nibble encodes a value in [0, 15] representing the original weight offset by +8. Mirrors the reference implementation's `quantize_row_q4_0_ref`.
  Param src: Source f32 values; length must be a positive multiple of 32.
  Param dst: Destination byte buffer; must be at least `(src.len / 32) * 18` bytes.
  Note: Asserts (debug builds only) that alignment and size preconditions hold.

- quantizeRowToQ8_0 [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dequant/#quantize-row-to-q8-0
  Signature: pub fn quantizeRowToQ8_0(src: []const f32, dst: []u8) void
  Summary: Quantize one row of f32 weights into the GGML `Q8_0` block layout.
  Description: Each 32-element block is stored as one f16 scale followed by 32 signed int8 values clamped to [-127, 127]; the scale is `max(|w|) / 127`. Mirrors the reference implementation's `quantize_row_q8_0_ref`.
  Param src: Source f32 values; length must be a positive multiple of 32.
  Param dst: Destination byte buffer; must be at least `(src.len / 32) * 34` bytes.
  Note: Asserts (debug builds only) that alignment and size preconditions hold.

- dotQ4KRow [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dequant/#dot-q4-krow
  Signature: pub fn dotQ4KRow(raw_data: []const u8, row_index: u32, cols: u32, input: []const f32) !f32
  Summary: Dot one Q4_K-packed row against an f32 input vector.
  Description: Q4_K stores 256 weights per super-block as 8 sub-blocks of 32 nibbles, each with its own 6-bit scale and min packed into a 12-byte header (plus block-level f16 `d`/`dmin`); validates block alignment and bounds, then delegates to the unchecked vectorized inner loop.
  Param raw_data: Raw Q4_K tensor bytes (144 bytes per 256-element super-block).
  Param row_index: Zero-based row to dot.
  Param cols: Number of columns; must be a multiple of 256.
  Param input: f32 input vector of length `>= cols`.
  Returns: The f32 dot product, or `error.UnsupportedShape` / `error.InputTooSmall` on misuse.

- fillInputSum32 [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dequant/#fill-input-sum32
  Signature: pub fn fillInputSum32(input: []const f32, sums: []f32) void
  Summary: Precompute per-32-element sums of an input vector for the `WithSum32` Q4_K/Q5_K dot paths.
  Description: Those paths fold the asymmetric min subtraction `-m * sum(x_block)` out of the inner loop, so the caller fills `sums[i] = sum(input[i*32 .. (i+1)*32])` once and reuses it across many rows.
  Param input: Input vector whose length must be a positive multiple of 32.
  Param sums: Destination of length `>= input.len / 32`; lane `i` receives the sum of input block `i`.

- dotQ5KRow [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dequant/#dot-q5-krow
  Signature: pub fn dotQ5KRow(raw_data: []const u8, row_index: u32, cols: u32, input: []const f32) !f32
  Summary: Dot one Q5_K-packed row against an f32 input vector.
  Description: Q5_K extends Q4_K with a 5th high-bit plane stored as 32 bytes (one bit per weight, eight 32-element sub-blocks); validates block alignment and bounds, then delegates to the unchecked vectorized inner loop.
  Param raw_data: Raw Q5_K tensor bytes (176 bytes per 256-element super-block).
  Param row_index: Zero-based row to dot.
  Param cols: Number of columns; must be a multiple of 256.
  Param input: f32 input vector of length `>= cols`.
  Returns: The f32 dot product, or `error.UnsupportedShape` / `error.InputTooSmall` on misuse.

- dotQ6KRow [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dequant/#dot-q6-krow
  Signature: pub fn dotQ6KRow(raw_data: []const u8, row_index: u32, cols: u32, input: []const f32) !f32
  Summary: Dot one Q6_K-packed row against an f32 input vector.
  Description: Q6_K packs 256 6-bit weights as a low-nibble plane plus a 2-bit-per-weight high plane, with one f16 super-block scale and eight signed-int8 per-32 sub-scales; weights are recentered by `-32`. Validates block alignment and bounds, then delegates to the unchecked vectorized inner loop.
  Param raw_data: Raw Q6_K tensor bytes (210 bytes per 256-element super-block).
  Param row_index: Zero-based row to dot.
  Param cols: Number of columns; must be a multiple of 256.
  Param input: f32 input vector of length `>= cols`.
  Returns: The f32 dot product, or `error.UnsupportedShape` / `error.InputTooSmall` on misuse.

### Module: Embed
URL: https://zolotukhin.ai/zinc/docs/zig-api/embed/
Source: src/zinc_rt/isa/cpu_zig/embed.zig
Code lines: 32
Summary: T-CPU EMBED implementation.
Overview: Reads one token row from a GGUF tensor into f32 hidden state.

- Params [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/embed/#params
  Signature: pub const Params = struct
  Summary: Inputs and outputs for one EMBED call.
  Param raw_data: Raw GGUF tensor bytes for the embedding matrix `[vocab_size, hidden_dim]`.
  Param tensor_type: GGML quantization format of `raw_data` (forwarded to `dequant.row`).
  Param token_id: Row index to fetch; must be `< vocab_size`.
  Param hidden_dim: Number of columns per row; also the required length of `output`.
  Param vocab_size: Number of embedding rows in `raw_data`.
  Param output: Destination hidden-state slice of length exactly `hidden_dim`.

- run [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/embed/#run
  Signature: pub fn run(params: Params) !void
  Summary: Dequantize the row at `params.token_id` of the embedding matrix into `params.output`.
  Description: Thin wrapper over `dequant.row` that validates the token index and output shape. the output slice does not match `hidden_dim`, otherwise void.
  Param params: Token id, matrix shape, and destination slice; see `Params`.
  Returns: `error.TokenOutOfRange` when the token id is past `vocab_size`, `error.ShapeMismatch` when

### Module: Flash Attn
URL: https://zolotukhin.ai/zinc/docs/zig-api/flash-attn/
Source: src/zinc_rt/isa/cpu_zig/flash_attn.zig
Code lines: 89
Summary: T-CPU flash attention (single-query decode) implementation.
Overview: Computes scaled dot-product attention over a KV cache for one query token.

- Params [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/flash-attn/#params
  Signature: pub const Params = struct
  Summary: Inputs and outputs for one single-query flash attention call.
  Param q: Query vector packed `[n_heads, head_dim]` for the current decode token.
  Param kv_k: Key cache packed `[seq_len, n_kv_heads, head_dim]`.
  Param kv_v: Value cache packed `[seq_len, n_kv_heads, head_dim]`.
  Param output: Attention output packed `[n_heads, head_dim]`.
  Param n_heads: Number of query heads.
  Param n_kv_heads: Number of key/value heads (GQA: `n_heads / n_kv_heads` queries share each KV head).
  Param head_dim: Per-head feature dimension.
  Param seq_len: Number of cached key/value positions to attend over.
  Param attn_sinks: Per-head sink logits added to the softmax denominator; NaN disables a head's sink.
  Param scratch_scores: Caller-owned scratch of length `>= seq_len` for raw scores.
  Param scratch_probs: Caller-owned scratch of length `>= seq_len` for exponentiated weights.

- run [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/flash-attn/#run
  Signature: pub fn run(params: Params) !void
  Summary: Compute single-query scaled dot-product attention with optional per-head softmax sinks.
  Description: For each query head: dots `q` against the cached keys, applies a `1/sqrt(head_dim)` scale, max-subtracted softmax (folding in the sink if finite), then writes the value-weighted sum to the matching slot of `output`. GQA is supported via `q_per_kv = n_heads / n_kv_heads`. slots are smaller than `seq_len` or `head_dim` is zero, otherwise void.
  Param params: Query, KV cache, attention sinks, scratch buffers, and output slice; see `Params`.
  Returns: `error.EmptyInput` when query or output is empty, `error.ShapeMismatch` when scratch

### Module: Lm Head
URL: https://zolotukhin.ai/zinc/docs/zig-api/lm-head/
Source: src/zinc_rt/isa/cpu_zig/lm_head.zig
Code lines: 43
Summary: T-CPU LM_HEAD implementation.
Overview: Projects hidden state through a GGUF output matrix and writes logits.

- Params [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/lm-head/#params
  Signature: pub const Params = struct
  Summary: Inputs and outputs for one LM_HEAD call.
  Param raw_data: Raw GGUF tensor bytes for the output matrix `[vocab_size, hidden_dim]`.
  Param tensor_type: GGML quantization format of `raw_data` (forwarded to `dequant.row`).
  Param hidden: Final hidden state of length `hidden_dim`.
  Param row_scratch: Caller-owned scratch buffer of length exactly `hidden_dim` for one dequantized row.
  Param logits: Destination vector of length `vocab_size`; row `i` of the matrix maps to `logits[i]`.

- run [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/lm-head/#run
  Signature: pub fn run(params: Params) !void
  Summary: Project the hidden state through every row of the GGUF output matrix to produce vocab logits.
  Description: Rows are dequantized one at a time into `row_scratch` and dot-multiplied with `hidden`. `row_scratch` is not exactly `hidden.len`, otherwise void.
  Param params: Tensor data, hidden state, scratch row, and logits slice; see `Params`.
  Returns: `error.EmptyInput` when either `hidden` or `logits` is empty, `error.ShapeMismatch` when

### Module: Matvec
URL: https://zolotukhin.ai/zinc/docs/zig-api/matvec/
Source: src/zinc_rt/isa/cpu_zig/matvec.zig
Code lines: 68
Summary: T-CPU matrix-vector projection implementation.
Overview: Dequantizes one GGUF tensor row at a time and computes a scalar matvec.

- Params [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/matvec/#params
  Signature: pub const Params = struct
  Summary: Inputs and outputs for one matrix-vector projection.
  Param raw_data: Raw GGUF tensor bytes for the weight matrix `[rows, cols]`.
  Param tensor_type: GGML quantization format of `raw_data` (forwarded to `dequant.row`).
  Param input: Input vector of length `cols`.
  Param row_scratch: Caller-owned scratch of length `>= cols` used to materialize one dequantized row.
  Param output: Destination vector of length `rows`; row `i` of the matrix lands in `output[i]`.
  Param accumulate: When true, add into `output` instead of overwriting (e.g. for MoE expert mixing).

- run [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/matvec/#run
  Signature: pub fn run(params: Params) !void
  Summary: Compute `output = W * input` (or `output += W * input` when `accumulate` is set) one row at a time.
  Description: Each row of the GGUF matrix is dequantized into `row_scratch` and dotted against `input`. `row_scratch` is shorter than `input`, otherwise void.
  Param params: Tensor data, input vector, scratch row, and output slice; see `Params`.
  Returns: `error.EmptyInput` when input or output is empty, `error.ShapeMismatch` when

### Module: Mod
URL: https://zolotukhin.ai/zinc/docs/zig-api/mod/
Source: src/zinc_rt/isa/cpu_zig/mod.zig
Code lines: 6
Summary: Pure Zig T-CPU opcode implementations.
Overview: The modules exported here are clarity-first reference kernels used by the CPU ring and by future cross-tier validation tests.

- rms_norm [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/mod/#rms-norm
  Signature: pub const rms_norm = @import("rms_norm.zig")
  Summary: Scalar RMS normalization with learned per-channel weight, used as the CPU oracle for layer norm.

- swiglu [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/mod/#swiglu
  Signature: pub const swiglu = @import("swiglu.zig")
  Summary: Scalar SwiGLU activation (`silu(gate) * up`) used by dense and MoE MLP paths.

- argmax [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/mod/#argmax
  Signature: pub const argmax = @import("argmax.zig")
  Summary: Deterministic argmax over a logits vector; picks the lowest index on ties.

- dequant [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/mod/#dequant
  Signature: pub const dequant = @import("dequant.zig")
  Summary: Shared GGML row dequantization and quantized row dot-product helpers consumed by other CPU ops.

- embed [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/mod/#embed
  Signature: pub const embed = @import("embed.zig")
  Summary: Token embedding lookup: dequantize one row of a GGUF embedding matrix into f32 hidden state.

- lm_head [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/mod/#lm-head
  Signature: pub const lm_head = @import("lm_head.zig")
  Summary: LM head projection: multiply a GGUF output matrix by the final hidden state to produce vocab logits.

### Module: Moe Gate Topk
URL: https://zolotukhin.ai/zinc/docs/zig-api/moe-gate-topk/
Source: src/zinc_rt/isa/cpu_zig/moe_gate_topk.zig
Code lines: 168
Summary: T-CPU MOE_GATE_TOPK implementation.
Overview: Computes router logits from a GGUF gate matrix, then selects and normalizes the active expert weights using the same routing rules as the Vulkan path.

- RoutingRule [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/moe-gate-topk/#routing-rule
  Signature: pub const RoutingRule = enum
  Summary: Selection rule applied after the router projection to convert logits into expert weights.

- Params [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/moe-gate-topk/#params
  Signature: pub const Params = struct
  Summary: Inputs and outputs for one MoE gate + top-k call.
  Param raw_data: Raw GGUF tensor bytes for the router matrix `[num_experts, hidden_dim]`.
  Param tensor_type: GGML quantization format of `raw_data` (forwarded to `dequant.row`).
  Param hidden: Hidden state of length `hidden_dim`.
  Param row_scratch: Caller-owned scratch of length `>= hidden_dim` for one dequantized router row.
  Param logits: Destination router logits of length `num_experts`; capped at 256 experts.
  Param k: Number of experts to select; must satisfy `1 <= k <= logits.len`.
  Param output_ids: Destination expert indices of length `>= k`.
  Param output_weights: Destination per-expert weights of length `>= k`, summing to 1 after the call.
  Param rule: Routing rule that decides how the top-k weights are computed (see `RoutingRule`).

- run [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/moe-gate-topk/#run
  Signature: pub fn run(params: Params) !void
  Summary: Project the hidden state through the router matrix, then select and normalize the top-k experts.
  Description: First fills `logits` row by row (matvec via `dequant.row`), then dispatches on `rule` to either `softmax_all` (softmax across all experts, pick top-k, renormalize) or `softmax_selected` (pick top-k by raw logit, softmax across that subset). `error.InvalidTopK` when `k` is zero or larger than the expert count, `error.ShapeMismatch` when scratch or output slices are too small, otherwise void.
  Param params: Router weights, hidden state, scratch buffers, selection size, and outputs; see `Params`.
  Returns: `error.EmptyInput` for empty inputs, `error.TooManyExperts` when `logits.len > 256`,

### Module: Residual Rms Norm
URL: https://zolotukhin.ai/zinc/docs/zig-api/residual-rms-norm/
Source: src/zinc_rt/isa/cpu_zig/residual_rms_norm.zig
Code lines: 59
Summary: T-CPU residual add + RMS norm implementation.
Overview: Computes: output = weight * rms_norm(x + residual)

- Params [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/residual-rms-norm/#params
  Signature: pub const Params = struct
  Summary: Inputs and outputs for one fused residual-add + RMS-norm call.
  Param x: Hidden state to normalize after residual addition.
  Param residual: Residual contribution added element-wise to `x` before normalization.
  Param weight: Per-channel learned scale applied after RMS normalization.
  Param output: Destination hidden state of length `>= x.len`.
  Param eps: Small constant added inside the square root to keep division numerically stable.

- run [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/residual-rms-norm/#run
  Signature: pub fn run(params: Params) !void
  Summary: Compute `output = weight * (x + residual) / sqrt(mean((x + residual)^2) + eps)`.
  Description: Fuses the post-attention/post-MLP residual add with the RMS norm so the sum lives only in registers; matches the GPU kernel that the Vulkan path uses on the decode hot loop. companion slice is shorter than `x`, otherwise void.
  Param params: Inputs, residual, learned scale, output slice, and `eps`; see `Params`.
  Returns: `error.EmptyInput` when inputs are zero-length, `error.ShapeMismatch` when any

### Module: Rms Norm
URL: https://zolotukhin.ai/zinc/docs/zig-api/rms-norm/
Source: src/zinc_rt/isa/cpu_zig/rms_norm.zig
Code lines: 35
Summary: T-CPU RMS_NORM implementation.
Overview: This is the scalar reference for RMS normalization and intentionally favors exactness and readable shape checks over throughput.

- Params [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/rms-norm/#params
  Signature: pub const Params = struct
  Summary: Inputs and outputs for one RMS_NORM call.
  Param input: Vector to normalize.
  Param weight: Per-channel learned scale; must match `input` in length.
  Param output: Destination vector; must match `input` in length.
  Param eps: Small constant added inside the square root to keep division numerically stable.

- run [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/rms-norm/#run
  Signature: pub fn run(params: Params) !void
  Summary: Compute `output[i] = weight[i] * input[i] / sqrt(mean(input^2) + eps)`.
  Description: Scalar reference implementation; favors readable shape checks and bit-stable math over throughput. `output` do not exactly match `input.len`, otherwise void.
  Param params: Input, learned scale, output slice, and `eps`; see `Params`.
  Returns: `error.EmptyInput` when `input` is zero-length, `error.ShapeMismatch` when `weight` or

### Module: Rope
URL: https://zolotukhin.ai/zinc/docs/zig-api/rope/
Source: src/zinc_rt/isa/cpu_zig/rope.zig
Code lines: 59
Summary: T-CPU RoPE (Rotary Positional Embedding) implementation.
Overview: Applies in-place rotary embeddings to query or key head data.

- Params [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/rope/#params
  Signature: pub const Params = struct
  Summary: Inputs for one in-place RoPE pass over a Q or K tensor.
  Param data: Mutable head-major buffer; head `h` lives at `data[h * stride ..][0..rope_dim]`.
  Param stride: Distance in floats between successive heads in `data`.
  Param rope_dim: Number of contiguous dimensions per head touched by RoPE (must be even).
  Param n_heads: Number of heads to rotate.
  Param position: Absolute token position used to compute the rotation angle.
  Param inv_freq: Inverse frequencies of length `rope_dim / 2`; missing entries default to zero (no rotation).

- run [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/rope/#run
  Signature: pub fn run(params: Params) !void
  Summary: Apply rotary positional embeddings in place to every head in `params.data`.
  Description: For each head and each frequency pair `(a, b) = (data[i], data[i + rope_dim/2])`, rotates by `theta = position * inv_freq[i]`: writes `(a*cos - b*sin, a*sin + b*cos)`. Uses the half-rotation layout (NeoX-style), matching the Vulkan kernels.
  Param params: Buffer, stride, rope dim, head count, position, and `inv_freq` table; see `Params`.
  Returns: `error.EmptyInput` when `data` is zero-length, otherwise void.

### Module: Sigmoid Mul
URL: https://zolotukhin.ai/zinc/docs/zig-api/sigmoid-mul/
Source: src/zinc_rt/isa/cpu_zig/sigmoid_mul.zig
Code lines: 30
Summary: T-CPU sigmoid-gated multiply implementation.
Overview: Computes: output[i] = sigmoid(gate[i]) * x[i] Used for attention gating (Q-gate) and SSM gated norm.

- Params [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/sigmoid-mul/#params
  Signature: pub const Params = struct
  Summary: Inputs and outputs for one sigmoid-gated multiply.
  Param gate: Pre-activation gate values; sigmoid is applied element-wise.
  Param x: Companion values multiplied by the sigmoid of `gate`.
  Param output: Destination vector of length `>= gate.len`.

- run [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/sigmoid-mul/#run
  Signature: pub fn run(params: Params) !void
  Summary: Compute `output[i] = sigmoid(gate[i]) * x[i]` for every gate element.
  Description: Used by attention Q-gating and SSM gated-norm paths where a learned scalar selects how much of `x` to pass through. is shorter than `gate`, otherwise void.
  Param params: Gate, value, and output slices; see `Params`.
  Returns: `error.EmptyInput` when `gate` is empty, `error.ShapeMismatch` when `output` or `x`

### Module: Swiglu
URL: https://zolotukhin.ai/zinc/docs/zig-api/swiglu/
Source: src/zinc_rt/isa/cpu_zig/swiglu.zig
Code lines: 23
Summary: T-CPU SwiGLU implementation.
Overview: This is the scalar reference activation used by MoE and dense MLP paths before tier-specific kernels are trusted.

- Params [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/swiglu/#params
  Signature: pub const Params = struct
  Summary: Inputs and outputs for one SwiGLU activation.
  Param gate: Gate-projection vector fed through SiLU.
  Param up: Up-projection vector multiplied by the SiLU-gated values.
  Param output: Destination vector; all three slices must be the same length.

- run [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/swiglu/#run
  Signature: pub fn run(params: Params) !void
  Summary: Compute `output[i] = silu(gate[i]) * up[i]` where `silu(x) = x / (1 + exp(-x))`.
  Description: Reference SwiGLU used by MoE and dense MLP paths to validate tier-specific kernels.
  Param params: Gate, up, and output slices of equal length; see `Params`.
  Returns: `error.ShapeMismatch` when the three slices differ in length, otherwise void.

### Module: Vadd
URL: https://zolotukhin.ai/zinc/docs/zig-api/vadd/
Source: src/zinc_rt/isa/cpu_zig/vadd.zig
Code lines: 27
Summary: T-CPU element-wise vector addition implementation.
Overview: Computes: output[i] = a[i] + b[i]

- Params [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/vadd/#params
  Signature: pub const Params = struct
  Summary: Inputs and outputs for one element-wise vector addition.
  Param a: First operand vector.
  Param b: Second operand vector of length `>= a.len`.
  Param output: Destination vector of length `>= a.len`.

- run [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/vadd/#run
  Signature: pub fn run(params: Params) !void
  Summary: Compute `output[i] = a[i] + b[i]` for the first `a.len` elements.
  Description: Trailing elements of `b` and `output` are ignored, so callers may pass over-sized buffers. is shorter than `a`, otherwise void.
  Param params: Operand and destination slices; see `Params`.
  Returns: `error.EmptyInput` when `a` is empty, `error.ShapeMismatch` when `output` or `b`

### Module: Kmd
URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/
Source: src/zinc_rt/kmd.zig
Code lines: 390
Summary: Thin AMDGPU kernel-driver queries used by direct ZINC_RT tiers.
Overview: This file intentionally starts with capability discovery only. T2 UMQ queue creation needs the same UAPI definitions, but selection must first prove the kernel exposes compute user queues instead of relying on kernel version alone.

- QueryStatus [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#query-status
  Signature: pub const QueryStatus = enum
  Summary: Outcome of probing the AMDGPU render node for compute user-queue support.
  Description: Each variant maps to a specific failure mode when discovering whether the kernel exposes the UMQ surface ZINC_RT tier 2 needs.

- ComputeUserqInfo [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#compute-userq-info
  Signature: pub const ComputeUserqInfo = struct
  Summary: Compute user-queue capability metadata reported by the kernel.
  Description: Captures the slot count and the EOP (end-of-pipe) scratch buffer sizing the driver requires when creating a compute UMQ.

- QueryResult [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#query-result
  Signature: pub const QueryResult = struct
  Summary: Combined result returned by `queryComputeUserq`.
  Description: Carries the discovery status plus optional capability info and the errno captured from the failing ioctl, when applicable.

- AMDGPU_HW_IP_COMPUTE [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#amdgpu-hw-ip-compute
  Signature: pub const AMDGPU_HW_IP_COMPUTE: u32 = 1
  Summary: AMDGPU HW IP type selector for the compute pipe used by `AMDGPU_INFO` queries.

- AMDGPU_INFO_HW_IP_INFO [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#amdgpu-info-hw-ip-info
  Signature: pub const AMDGPU_INFO_HW_IP_INFO: u32 = 0x02
  Summary: `AMDGPU_INFO` sub-query that returns `DrmAmdgpuInfoHwIp` for a given HW IP.

- AMDGPU_INFO_UQ_FW_AREAS [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#amdgpu-info-uq-fw-areas
  Signature: pub const AMDGPU_INFO_UQ_FW_AREAS: u32 = 0x24
  Summary: `AMDGPU_INFO` sub-query that returns user-queue firmware area metadata (`DrmAmdgpuInfoUqMetadata`).

- AMDGPU_USERQ_OP_CREATE [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#amdgpu-userq-op-create
  Signature: pub const AMDGPU_USERQ_OP_CREATE: u32 = 1
  Summary: `DRM_AMDGPU_USERQ` op code that allocates a new user-mode queue.

- AMDGPU_USERQ_OP_FREE [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#amdgpu-userq-op-free
  Signature: pub const AMDGPU_USERQ_OP_FREE: u32 = 2
  Summary: `DRM_AMDGPU_USERQ` op code that releases a previously created user-mode queue.

- AMDGPU_GEM_DOMAIN_GTT [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#amdgpu-gem-domain-gtt
  Signature: pub const AMDGPU_GEM_DOMAIN_GTT: u64 = 0x2
  Summary: GEM domain flag requesting allocation in system GTT memory.

- AMDGPU_GEM_DOMAIN_VRAM [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#amdgpu-gem-domain-vram
  Signature: pub const AMDGPU_GEM_DOMAIN_VRAM: u64 = 0x4
  Summary: GEM domain flag requesting allocation in device VRAM.

- AMDGPU_GEM_DOMAIN_DOORBELL [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#amdgpu-gem-domain-doorbell
  Signature: pub const AMDGPU_GEM_DOMAIN_DOORBELL: u64 = 0x40
  Summary: GEM domain flag requesting allocation in the MMIO doorbell aperture.

- AMDGPU_GEM_CREATE_CPU_GTT_USWC [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#amdgpu-gem-create-cpu-gtt-uswc
  Signature: pub const AMDGPU_GEM_CREATE_CPU_GTT_USWC: u64 = 1 << 2
  Summary: GEM creation flag asking the kernel to map GTT memory as CPU write-combined for fast streaming writes.

- AMDGPU_GEM_CREATE_VRAM_CLEARED [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#amdgpu-gem-create-vram-cleared
  Signature: pub const AMDGPU_GEM_CREATE_VRAM_CLEARED: u64 = 1 << 3
  Summary: GEM creation flag asking the kernel to zero-fill VRAM allocations before returning the BO.

- AMDGPU_GEM_CREATE_CPU_ACCESS_REQUIRED [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#amdgpu-gem-create-cpu-access-required
  Signature: pub const AMDGPU_GEM_CREATE_CPU_ACCESS_REQUIRED: u64 = 1 << 0
  Summary: GEM creation flag requiring the VRAM allocation to land in the CPU-visible BAR aperture so the BO can be mmap'd and written by the host (needs large / resizable BAR for allocations beyond the legacy 256 MiB window).

- AMDGPU_GEM_CREATE_VM_ALWAYS_VALID [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#amdgpu-gem-create-vm-always-valid
  Signature: pub const AMDGPU_GEM_CREATE_VM_ALWAYS_VALID: u64 = 1 << 6
  Summary: GEM creation flag keeping the BO permanently mapped in the device VM so it never needs revalidation.

- AMDGPU_VA_OP_MAP [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#amdgpu-va-op-map
  Signature: pub const AMDGPU_VA_OP_MAP: u32 = 1
  Summary: `DRM_AMDGPU_GEM_VA` operation that binds a BO into the device virtual address space.

- AMDGPU_VM_PAGE_READABLE [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#amdgpu-vm-page-readable
  Signature: pub const AMDGPU_VM_PAGE_READABLE: u32 = 1 << 1
  Summary: VA mapping flag granting GPU read access to the mapped range.

- AMDGPU_VM_PAGE_WRITEABLE [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#amdgpu-vm-page-writeable
  Signature: pub const AMDGPU_VM_PAGE_WRITEABLE: u32 = 1 << 2
  Summary: VA mapping flag granting GPU write access to the mapped range.

- AMDGPU_VM_PAGE_EXECUTABLE [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#amdgpu-vm-page-executable
  Signature: pub const AMDGPU_VM_PAGE_EXECUTABLE: u32 = 1 << 3
  Summary: VA mapping flag granting GPU shader-execute access to the mapped range.

- AMDGPU_VM_MTYPE_DEFAULT [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#amdgpu-vm-mtype-default
  Signature: pub const AMDGPU_VM_MTYPE_DEFAULT: u32 = 0 << 5
  Summary: VA mapping flag selecting the default memory type (MTYPE) for the GPU page table entry.

- DrmAmdgpuGemCreateIn [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#drm-amdgpu-gem-create-in
  Signature: pub const DrmAmdgpuGemCreateIn = extern struct
  Summary: Input layout for the `DRM_IOCTL_AMDGPU_GEM_CREATE` ioctl.
  Description: Mirrors the kernel UAPI struct describing the requested buffer size, alignment, domain mask, and creation flags.

- DrmAmdgpuGemCreateOut [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#drm-amdgpu-gem-create-out
  Signature: pub const DrmAmdgpuGemCreateOut = extern struct
  Summary: Output layout returned by `DRM_IOCTL_AMDGPU_GEM_CREATE`, holding the freshly allocated BO handle.

- DrmAmdgpuGemCreate [union]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#drm-amdgpu-gem-create
  Signature: pub const DrmAmdgpuGemCreate = extern union
  Summary: Tagged union packing the in/out forms of the GEM-create ioctl into the same buffer the kernel reads and writes.

- DrmAmdgpuGemMmapIn [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#drm-amdgpu-gem-mmap-in
  Signature: pub const DrmAmdgpuGemMmapIn = extern struct
  Summary: Input layout for `DRM_IOCTL_AMDGPU_GEM_MMAP`, identifying the BO to expose to userspace.

- DrmAmdgpuGemMmapOut [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#drm-amdgpu-gem-mmap-out
  Signature: pub const DrmAmdgpuGemMmapOut = extern struct
  Summary: Output layout returned by `DRM_IOCTL_AMDGPU_GEM_MMAP` with the file offset to pass to `mmap`.

- DrmAmdgpuGemMmap [union]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#drm-amdgpu-gem-mmap
  Signature: pub const DrmAmdgpuGemMmap = extern union
  Summary: Tagged union packing the in/out forms of the GEM-mmap ioctl into one shared buffer.

- DrmAmdgpuGemVa [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#drm-amdgpu-gem-va
  Signature: pub const DrmAmdgpuGemVa = extern struct
  Summary: Argument layout for `DRM_IOCTL_AMDGPU_GEM_VA`, the ioctl that maps a BO into the GPU virtual address space.
  Description: Encodes the BO handle, VA operation, page-permission flags, target VA range, and any syncobj fence handles.

- DrmAmdgpuInfo [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#drm-amdgpu-info
  Signature: pub const DrmAmdgpuInfo = extern struct
  Summary: Argument layout for `DRM_IOCTL_AMDGPU_INFO`, the generic info-query ioctl.
  Description: `return_pointer`/`return_size` describe a userspace output buffer; `query` selects a sub-query whose discriminator-specific parameters live in `query_data`.

- DrmAmdgpuInfoHwIp [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#drm-amdgpu-info-hw-ip
  Signature: pub const DrmAmdgpuInfoHwIp = extern struct
  Summary: Output buffer for `AMDGPU_INFO_HW_IP_INFO`.
  Description: Reports the HW IP version and capabilities, ring-buffer alignment requirements, the bitmask of available kernel rings, and the count of user-queue slots — tier 2 checks both `available_rings` and `userq_num_slots` to confirm UMQ support.

- DrmAmdgpuInfoUqMetadata [union]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#drm-amdgpu-info-uq-metadata
  Signature: pub const DrmAmdgpuInfoUqMetadata = extern union
  Summary: Output buffer for `AMDGPU_INFO_UQ_FW_AREAS`, sized per IP type.
  Description: Reports the per-queue scratch buffers the firmware needs: shadow/CSA areas for GFX, the EOP buffer for compute, and the CSA area for SDMA.

- DrmAmdgpuUserqIn [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#drm-amdgpu-userq-in
  Signature: pub const DrmAmdgpuUserqIn = extern struct
  Summary: Input layout for the `DRM_IOCTL_AMDGPU_USERQ` ioctl.
  Description: Describes the create/free op, the target IP (compute, gfx, sdma), the doorbell BO handle and slot offset within it, the VA ranges of the queue ring buffer plus its read/write pointers, and a pointer to the IP-specific MQD blob.

- DrmAmdgpuUserqOut [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#drm-amdgpu-userq-out
  Signature: pub const DrmAmdgpuUserqOut = extern struct
  Summary: Output layout returned by a successful `AMDGPU_USERQ_OP_CREATE`, containing the kernel-assigned queue id used by subsequent ioctls.

- DrmAmdgpuUserq [union]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#drm-amdgpu-userq
  Signature: pub const DrmAmdgpuUserq = extern union
  Summary: Tagged union packing the in/out forms of the user-queue ioctl into the same buffer.

- DrmAmdgpuUserqMqdComputeGfx11 [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#drm-amdgpu-userq-mqd-compute-gfx11
  Signature: pub const DrmAmdgpuUserqMqdComputeGfx11 = extern struct
  Summary: GFX11 compute MQD payload pointed at by `DrmAmdgpuUserqIn.mqd`.
  Description: Currently only the EOP scratch VA is required; matches the kernel's `drm_amdgpu_userq_mqd_compute_gfx11` layout.

- Bo [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#bo
  Signature: pub const Bo = struct
  Summary: Thin handle for a kernel-managed GEM buffer object.
  Description: Pairs the kernel GEM handle with the allocation size so callers can re-issue ioctls (mmap, VA map) without re-querying the size.

- queryComputeUserq [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#query-compute-userq
  Signature: pub fn queryComputeUserq(render_node: []const u8) QueryResult
  Summary: Probe an AMDGPU render node to decide whether the compute user-mode-queue surface is usable.
  Description: Opens the render node, asks the kernel for compute HW IP info plus user-queue firmware areas, and validates that the queue slots and EOP buffer parameters look sane.
  Param render_node: Absolute path to the DRI render node (e.g. `/dev/dri/renderD128`).
  Returns: A `QueryResult` whose `status` field identifies the precise failure mode or `.available` on success, with `info` populated when compute UMQ is ready to use.
  Note: Returns `.unsupported_os` immediately on non-Linux builds without opening any file.

- queryHwIp [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#query-hw-ip
  Signature: pub fn queryHwIp(file: std.fs.File, ip_type: u32) !DrmAmdgpuInfoHwIp
  Summary: Issue `AMDGPU_INFO_HW_IP_INFO` for the given HW IP type on an open render-node file.
  Param file: Open file handle for the AMDGPU render node.
  Param ip_type: IP selector constant such as `AMDGPU_HW_IP_COMPUTE`.
  Returns: The kernel-filled `DrmAmdgpuInfoHwIp` for IP instance 0.
  Note: Returns `error.IoctlFailed` on failure; inspect `lastErrno()` for the captured errno.

- createGem [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#create-gem
  Signature: pub fn createGem(file: std.fs.File, size: u64, alignment: u64, domains: u64, flags: u64) !Bo
  Summary: Allocate a GEM buffer object via `DRM_IOCTL_AMDGPU_GEM_CREATE`.
  Param file: Open file handle for the AMDGPU render node.
  Param size: Buffer size in bytes.
  Param alignment: Required base alignment in bytes.
  Param domains: Bitmask of `AMDGPU_GEM_DOMAIN_*` constants selecting GTT, VRAM, or doorbell aperture.
  Param flags: Bitmask of `AMDGPU_GEM_CREATE_*` creation flags (e.g. USWC, VRAM-cleared, always-valid).
  Returns: A `Bo` wrapping the kernel GEM handle and the requested size for later mmap or VA-map calls.

- mmapGem [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#mmap-gem
  Signature: pub fn mmapGem(file: std.fs.File, bo: Bo, prot: u32) ![]align(std.heap.page_size_min) u8
  Summary: Map a previously created GEM BO into the calling process's address space.
  Description: First queries the kernel for the BO's mmap offset, then issues a shared `mmap` against the render-node fd at that offset.
  Param file: Open file handle for the AMDGPU render node that owns the BO.
  Param bo: The buffer object handle and size returned by `createGem`.
  Param prot: Standard POSIX `PROT_*` page-protection flags.
  Returns: A page-aligned byte slice covering the BO; the slice length equals `bo.size`.

- mapGemVa [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#map-gem-va
  Signature: pub fn mapGemVa(file: std.fs.File, bo: Bo, va: u64, flags: u32) !void
  Summary: Bind a GEM BO into the device virtual address space at a caller-chosen VA.
  Description: Performs an `AMDGPU_VA_OP_MAP` over the full BO size starting at offset 0.
  Param file: Open file handle for the AMDGPU render node that owns the BO.
  Param bo: The buffer object handle and size returned by `createGem`.
  Param va: Target GPU virtual address; must satisfy the page alignment the kernel enforces.
  Param flags: Bitmask of `AMDGPU_VM_PAGE_*` and `AMDGPU_VM_MTYPE_*` permission/cache flags.

- createComputeUserq [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#create-compute-userq
  Signature: pub fn createComputeUserq( file: std.fs.File, doorbell_handle: u32, doorbell_offset: u32, queue_va: u64, queue_size: u64, rptr_va: u64, wptr_va: u64, eop_va: u64, flags: u32, ) !u32
  Summary: Create a compute user-mode queue via `DRM_IOCTL_AMDGPU_USERQ`.
  Description: Builds a GFX11 compute MQD pointing at the caller-supplied EOP scratch VA and submits an `AMDGPU_USERQ_OP_CREATE`.
  Param file: Open file handle for the AMDGPU render node.
  Param doorbell_handle: GEM handle of the doorbell BO the kernel will use to wake this queue.
  Param doorbell_offset: Doorbell slot offset within the doorbell BO assigned to this queue.
  Param queue_va: Device VA of the ring buffer backing the queue.
  Param queue_size: Ring buffer size in bytes.
  Param rptr_va: Device VA of the queue read-pointer word.
  Param wptr_va: Device VA of the queue write-pointer word.
  Param eop_va: Device VA of the end-of-pipe scratch buffer required by GFX11 compute firmware.
  Param flags: Driver-specific creation flags forwarded as-is to the kernel.
  Returns: The kernel-assigned queue id used in later doorbell rings and the matching `freeUserq` call.

- freeUserq [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#free-userq
  Signature: pub fn freeUserq(file: std.fs.File, queue_id: u32) !void
  Summary: Release a user-mode queue previously returned by `createComputeUserq` via `AMDGPU_USERQ_OP_FREE`.
  Param file: Open file handle for the AMDGPU render node that owns the queue.
  Param queue_id: Kernel-assigned queue id to free.

- lastErrno [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kmd/#last-errno
  Signature: pub fn lastErrno() ?linux.E
  Summary: Return the errno captured by the most recent ioctl performed through this module.
  Returns: The captured `linux.E` value, or `null` if the previous call succeeded or no call has been made yet.
  Note: The module clears the saved errno at the start of every ioctl, so the value is only meaningful immediately after an `error.IoctlFailed`.

### Module: Lib
URL: https://zolotukhin.ai/zinc/docs/zig-api/lib/
Source: src/zinc_rt/lib.zig
Code lines: 18
Summary: ZINC_RT reference-runtime module.
Overview: Exposes the M0 engine, IR, CPU ring, and scalar CPU kernels through one importable package so `forward_zinc_rt` can exercise the runtime without pulling the same files into multiple Zig modules.

- engine [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/lib/#engine
  Signature: pub const engine = @import("engine.zig")
  Summary: Top-level runtime handle and tier-selection helpers.
  Description: Other zinc_rt submodules go through this surface to obtain the active execution tier (CPU reference, T1 PM4, T2 UMQ, Metal, etc.).

- ir_op [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/lib/#ir-op
  Signature: pub const ir_op = @import("ir/op.zig")
  Summary: IR opcode definitions used by the M0/M1 decode graph.
  Description: Op kinds are stable identifiers shared by the emitter and the validator.

- ir_graph [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/lib/#ir-graph
  Signature: pub const ir_graph = @import("ir/graph.zig")
  Summary: IR graph container — nodes plus their op/argument metadata.
  Description: `forward_zinc_rt` emits one of these per token before lowering to the tier the engine selected.

- kmd [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/lib/#kmd
  Signature: pub const kmd = @import("kmd.zig")
  Summary: Kernel-mode-driver glue.
  Description: Houses helpers and constants shared by the ring backends (UMQ user queues, KFD compute queues) so they describe submissions in one place.

- ring [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/lib/#ring
  Signature: pub const ring = @import("ring/mod.zig")
  Summary: Common ring-submission surface — what every concrete ring backend (CPU, UMQ, KFD, CS) implements so the engine can speak to them uniformly.

- cpu_ring [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/lib/#cpu-ring
  Signature: pub const cpu_ring = @import("ring/cpu.zig")
  Summary: Reference CPU ring used by the scalar M1 forward path.
  Description: Executes ops synchronously on the host so we have a ground-truth correctness oracle for the GPU rings.

- umq [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/lib/#umq
  Signature: pub const umq = @import("ring/umq.zig")
  Summary: T2 user-mode queue ring backed by `DRM_IOCTL_AMDGPU_USERQ`.
  Description: The "blessed" direct path when amdgpu firmware admits compute user queues.

- kfd [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/lib/#kfd
  Signature: pub const kfd = @import("ring/kfd.zig")
  Summary: T1 PM4 ring backed by `/dev/kfd` (the ROCm/tinygrad ABI).
  Description: Fallback when UMQ is rejected; talks PM4 packets to the compute scheduler directly.

- cs [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/lib/#cs
  Signature: pub const cs = @import("ring/cs.zig")
  Summary: Generic libdrm compute-stream submission used by the PM4 backends.
  Description: Wraps context create/submit so the ring backends share one BO/syncobj path.

- pm4_packet [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/lib/#pm4-packet
  Signature: pub const pm4_packet = @import("ring/packet.zig")
  Summary: PM4 packet builders (NOPs, indirect-buffer dispatch, COPY_DATA, fences).
  Description: Consumed by both the UMQ and KFD rings to produce wire-compatible command-buffer bytes.

- kernels [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/lib/#kernels
  Signature: pub const kernels = @import("isa/cpu_zig/mod.zig")
  Summary: Scalar CPU kernels (dequantization, matvec, softmax, etc.) used by the reference forward path and by GPU-tier correctness checks.

- fast_pool [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/lib/#fast-pool
  Signature: pub const fast_pool = @import("fast_pool.zig")
  Summary: Tiny fixed-size worker pool used to fan out per-layer / per-expert work in the scalar M1 decode path without paying allocator/scheduler overhead.

- batching [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/lib/#batching
  Signature: pub const batching = @import("batching.zig")
  Summary: Tenant-aware admission and batch-selection primitives for the M3 continuous-batching executor.

### Module: Cpu
URL: https://zolotukhin.ai/zinc/docs/zig-api/cpu/
Source: src/zinc_rt/ring/cpu.zig
Code lines: 20
Summary: T-CPU ring backend.
Overview: Walks packet batches and executes pure Zig kernels as the validation oracle used by every other ring tier (T1 PM4-direct, UMQ, Metal) to cross-check their outputs bit-for-bit against a reference run.

- CpuRing [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cpu/#cpu-ring
  Signature: pub const CpuRing = struct
  Summary: T-CPU ring backend that executes packet batches synchronously on the CPU.
  Description: dispatch is run by the pure Zig kernels in `isa/cpu_zig/mod.zig`.
  Note: Acts as the validation oracle for the GPU ring implementations; every
  - CpuRing.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cpu/#cpu-ring-init
    Signature: pub fn init() CpuRing
    Summary: Construct a fresh CPU ring.
    Description: The backend is stateless, so this is a trivial value initializer that exists to mirror the GPU ring API.
  - CpuRing.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cpu/#cpu-ring-deinit
    Signature: pub fn deinit(_: *CpuRing) void}
    Summary: Release any resources held by the ring.
    Description: No-op for the CPU backend.

### Module: Cs
URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/
Source: src/zinc_rt/ring/cs.zig
Code lines: 3070
Summary: AMDGPU DRM command-submission (CS) path — bring-up of the RADV / radeonsi PM4 submission foundation.
Overview: T1 PM4-direct reaches the AMD command processor through three Linux ABIs: * `DRM_IOCTL_AMDGPU_USERQ` — the user-mode-queue ABI; the bench-node firmware reports zero compute USERQ slots, so it is unusable here (see `umq.zig`). * `/dev/kfd` `AMDKFD_IOC_CREATE_QUEUE` + a doorbell ring — works to create a raw `QUEUE_TYPE_COMPUTE` queue, but the MES never retires the PM4 we stage in it on this kernel (see `kfd.zig`). * `DRM_IOCTL_AMDGPU_CS` — the kernel-managed command-submission UAPI every AMD userspace driver (RADV, radeonsi, amdvlk) rides. The kernel owns the ring / doorbell / MES bookkeeping; userspace hands it an indirect buffer (IB) of PM4 and waits on the retired fence. This is the reliable foundation the GPU compute dispatch lowers onto.
Overview: This module brings the CS path's first retired PM4 batch up as a benchmark-visible gate: open the render node, query the compute HW IP, allocate an amdgpu context, create a persistent BO list for a GTT indirect-buffer BO plus data/signal/shader BOs, map them into the GPU VM at low VAs, submit PM4 streams through `DRM_IOCTL_AMDGPU_CS` using the same context/BO list, and wait for the returned fences with `DRM_IOCTL_AMDGPU_WAIT_CS`.
Overview: This is not the final T1/T2 ring from the design; it is the kernel-managed CS baseline used to validate packet bytes, BO residency, VM mapping, and fence retirement before lowering real decode slices onto the direct tiers.

- default_render_node [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#default-render-node
  Signature: pub const default_render_node = "/dev/dri/renderD128"
  Summary: Default DRM render node used by the CS bring-up gate when no path is provided.

- AMDGPU_HW_IP_GFX [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#amdgpu-hw-ip-gfx
  Signature: pub const AMDGPU_HW_IP_GFX: u32 = 0
  Summary: amdgpu HW IP block id for the graphics ring (uapi/drm/amdgpu_drm.h).

- AMDGPU_HW_IP_COMPUTE [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#amdgpu-hw-ip-compute
  Signature: pub const AMDGPU_HW_IP_COMPUTE: u32 = 1
  Summary: amdgpu HW IP block id for the async compute ring used by ZINC submissions.

- AMDGPU_CTX_OP_ALLOC_CTX [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#amdgpu-ctx-op-alloc-ctx
  Signature: pub const AMDGPU_CTX_OP_ALLOC_CTX: u32 = 1
  Summary: `DRM_AMDGPU_CTX` op selector for allocating a new submission context.

- AMDGPU_CTX_OP_FREE_CTX [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#amdgpu-ctx-op-free-ctx
  Signature: pub const AMDGPU_CTX_OP_FREE_CTX: u32 = 2
  Summary: `DRM_AMDGPU_CTX` op selector for releasing a previously allocated context.

- AMDGPU_BO_LIST_OP_CREATE [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#amdgpu-bo-list-op-create
  Signature: pub const AMDGPU_BO_LIST_OP_CREATE: u32 = 0
  Summary: `DRM_AMDGPU_BO_LIST` op selector to create a residency BO list handle.

- AMDGPU_BO_LIST_OP_DESTROY [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#amdgpu-bo-list-op-destroy
  Signature: pub const AMDGPU_BO_LIST_OP_DESTROY: u32 = 1
  Summary: `DRM_AMDGPU_BO_LIST` op selector to destroy a previously created BO list.

- AMDGPU_CHUNK_ID_IB [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#amdgpu-chunk-id-ib
  Signature: pub const AMDGPU_CHUNK_ID_IB: u32 = 0x01
  Summary: CS chunk id for an indirect-buffer descriptor (`DrmAmdgpuCsChunkIb`).

- AMDGPU_CHUNK_ID_BO_HANDLES [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#amdgpu-chunk-id-bo-handles
  Signature: pub const AMDGPU_CHUNK_ID_BO_HANDLES: u32 = 0x06
  Summary: CS chunk id for an inline BO-handles list, an alternative to a pre-created BO list.

- AMDGPU_IB_FLAG_EMIT_MEM_SYNC [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#amdgpu-ib-flag-emit-mem-sync
  Signature: pub const AMDGPU_IB_FLAG_EMIT_MEM_SYNC: u32 = 1 << 6
  Summary: IB flag instructing the kernel to emit a memory-sync packet around the IB so writes from the BO list reach DRAM before/after the dispatch.

- DrmAmdgpuCtxIn [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#drm-amdgpu-ctx-in
  Signature: pub const DrmAmdgpuCtxIn = extern struct
  Summary: Input payload of `DRM_IOCTL_AMDGPU_CTX`: selects an op and carries the caller-supplied `ctx_id` and submission priority for that op.

- DrmAmdgpuCtxOutAlloc [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#drm-amdgpu-ctx-out-alloc
  Signature: pub const DrmAmdgpuCtxOutAlloc = extern struct
  Summary: Output payload of `AMDGPU_CTX_OP_ALLOC_CTX`: the kernel-assigned context id returned in the same `DrmAmdgpuCtx` union after a successful allocation.

- DrmAmdgpuCtxOutState [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#drm-amdgpu-ctx-out-state
  Signature: pub const DrmAmdgpuCtxOutState = extern struct
  Summary: Output payload of the `AMDGPU_CTX_OP_QUERY_STATE` op: GPU reset state and hang counter for the queried context (unused on the bring-up path).

- DrmAmdgpuCtx [union]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#drm-amdgpu-ctx
  Signature: pub const DrmAmdgpuCtx = extern union
  Summary: Tagged union passed to `DRM_IOCTL_AMDGPU_CTX` covering the input request and the two output shapes (alloc / query-state).

- DrmAmdgpuBoListIn [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#drm-amdgpu-bo-list-in
  Signature: pub const DrmAmdgpuBoListIn = extern struct
  Summary: Input payload of `DRM_IOCTL_AMDGPU_BO_LIST`: op selector plus a pointer to an array of `DrmAmdgpuBoListEntry` describing the BOs the submission must keep resident.

- DrmAmdgpuBoListOut [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#drm-amdgpu-bo-list-out
  Signature: pub const DrmAmdgpuBoListOut = extern struct
  Summary: Output payload of `AMDGPU_BO_LIST_OP_CREATE`: the kernel-assigned BO list handle referenced from subsequent CS submissions.

- DrmAmdgpuBoList [union]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#drm-amdgpu-bo-list
  Signature: pub const DrmAmdgpuBoList = extern union
  Summary: Tagged union passed to `DRM_IOCTL_AMDGPU_BO_LIST` covering input and output.

- DrmAmdgpuBoListEntry [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#drm-amdgpu-bo-list-entry
  Signature: pub const DrmAmdgpuBoListEntry = extern struct
  Summary: Single residency entry inside a BO list: the GEM handle to make resident and a kernel-visible priority hint for eviction.

- DrmAmdgpuCsChunk [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#drm-amdgpu-cs-chunk
  Signature: pub const DrmAmdgpuCsChunk = extern struct
  Summary: One chunk inside a `DRM_IOCTL_AMDGPU_CS` submission: a typed sub-payload (`chunk_id`, length in dwords, pointer to the chunk data).

- DrmAmdgpuCsIn [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#drm-amdgpu-cs-in
  Signature: pub const DrmAmdgpuCsIn = extern struct
  Summary: Input payload of `DRM_IOCTL_AMDGPU_CS`: binds a context, BO list and an array of typed chunks (the IB descriptor lives in one of those chunks).

- DrmAmdgpuCsOut [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#drm-amdgpu-cs-out
  Signature: pub const DrmAmdgpuCsOut = extern struct
  Summary: Output payload of `DRM_IOCTL_AMDGPU_CS`: the fence handle the caller waits on via `DRM_IOCTL_AMDGPU_WAIT_CS` for the submission to retire.

- DrmAmdgpuCs [union]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#drm-amdgpu-cs
  Signature: pub const DrmAmdgpuCs = extern union
  Summary: Tagged union passed to `DRM_IOCTL_AMDGPU_CS` covering input and output.

- DrmAmdgpuCsChunkIb [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#drm-amdgpu-cs-chunk-ib
  Signature: pub const DrmAmdgpuCsChunkIb = extern struct
  Summary: Chunk payload for `AMDGPU_CHUNK_ID_IB`: describes the indirect-buffer VA, its size in bytes, the target IP type/ring, and submission flags such as `AMDGPU_IB_FLAG_EMIT_MEM_SYNC`.

- DrmAmdgpuWaitCsIn [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#drm-amdgpu-wait-cs-in
  Signature: pub const DrmAmdgpuWaitCsIn = extern struct
  Summary: Input payload of `DRM_IOCTL_AMDGPU_WAIT_CS`: identifies the fence to wait on (by `handle`/`ctx_id` against a specific IP/ring) and the timeout.

- DrmAmdgpuWaitCsOut [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#drm-amdgpu-wait-cs-out
  Signature: pub const DrmAmdgpuWaitCsOut = extern struct
  Summary: Output payload of `DRM_IOCTL_AMDGPU_WAIT_CS`: zero on successful retirement, nonzero on timeout or fence error.

- DrmAmdgpuWaitCs [union]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#drm-amdgpu-wait-cs
  Signature: pub const DrmAmdgpuWaitCs = extern union
  Summary: Tagged union passed to `DRM_IOCTL_AMDGPU_WAIT_CS` covering input and output.

- ArgmaxRangeResult [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#argmax-range-result
  Signature: pub const ArgmaxRangeResult = struct
  Summary: Result produced by the ordered-score argmax row-range kernel.

- DmmvArgmaxResult [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#dmmv-argmax-result
  Signature: pub const DmmvArgmaxResult = struct
  Summary: Result produced by a quantized DMMV row-range kernel that performs its own in-kernel argmax over the computed rows.

- PendingDmmvQ4_0RowRangeParallelChunks [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#pending-dmmv-q4-0-row-range-parallel-chunks
  Signature: pub const PendingDmmvQ4_0RowRangeParallelChunks = struct
  Summary: In-flight Q4_0 row-range dispatch submitted through `DRM_IOCTL_AMDGPU_CS`.
  Description: Callers can overlap independent CPU work with this fence, then call `finish` before reusing the `TokenBoundary` maps or PM4 builder.
  - PendingDmmvQ4_0RowRangeParallelChunks.finish [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#pending-dmmv-q4-0-row-range-parallel-chunks-finish
    Signature: pub fn finish(self: PendingDmmvQ4_0RowRangeParallelChunks, output: []f32) !void
    Summary: Wait for the submitted CS fence, validate the signal sentinel, and copy the GPU-written row scores into `output`.
  - PendingDmmvQ4_0RowRangeParallelChunks.waitDiscard [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#pending-dmmv-q4-0-row-range-parallel-chunks-wait-discard
    Signature: pub fn waitDiscard(self: PendingDmmvQ4_0RowRangeParallelChunks) void
    Summary: Retire the fence when the caller must abandon the result after submit.

- ResidentDmmvQ4_0Rows [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#resident-dmmv-q4-0-rows
  Signature: pub const ResidentDmmvQ4_0Rows = struct
  Summary: Q4_0 row window staged once into the long-lived CS input BO.
  Description: This is still GTT-backed bring-up memory, not the final device-local weight residency model, but it lets the executed M1 LM-head proof stop copying the same weight rows into the dispatch scratch on every run.

- SmokeStatus [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#smoke-status
  Signature: pub const SmokeStatus = enum
  Summary: Outcome classification for the CS bring-up smoke gate.
  Description: Each variant maps to a specific failure point in the open → submit → wait pipeline, so the benchmark UI can attribute a regression to render-node access, kernel ABI mismatch, BO/VA setup, submission, or fence retirement.

- SmokeResult [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#smoke-result
  Signature: pub const SmokeResult = struct
  Summary: Structured result returned by the CS bring-up smoke gate.
  Description: Captures the rendezvous addresses, kernel-assigned handles, observed signal value, fence handles, and the final `SmokeStatus` so benchmark output can surface a precise failure mode without re-running the path.
  - SmokeResult.ok [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#smoke-result-ok
    Signature: pub fn ok(self: SmokeResult) bool
    Summary: Returns true when both PM4 submissions retired and the signal BO read back the expected sentinel value.

- TokenBoundary [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary
  Signature: pub const TokenBoundary = struct
  Summary: Per-token CS submission context for the PM4 bring-up tiers.
  Description: Owns the long-lived amdgpu context, BO list, and the GPU-mapped indirect- buffer / input / output / signal / shader buffers used by the `copyU32`, `argmaxTop2`, `rmsNormElement0` and `dmmvF32RowRange` dispatches. Reused across many submissions so each decode step only re-records PM4 into the existing IB and re-submits via `DRM_IOCTL_AMDGPU_CS`.
  - TokenBoundary.initDefault [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-init-default
    Signature: pub fn initDefault() !TokenBoundary
    Summary: Open the canonical render node (`default_render_node`) and finish the full CS bring-up: context, BO list, IB / input / output / signal / shader buffers, all mapped into a low GPU VA range.
    Returns: A ready `TokenBoundary` whose `builder` can record PM4 immediately.
  - TokenBoundary.initPath [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-init-path
    Signature: pub fn initPath(render_node: []const u8) !TokenBoundary
    Summary: Open the given render node and bring up the full CS submission state.
    Description: Allocates an amdgpu context, creates GTT-backed BOs for the indirect buffer, input scratch (~2 MiB), output, signal and shader pages, maps each into a fixed low GPU VA so the kernel does not need to re-bind them per submission, uploads the gfx1201 PM4 kernels into the shader page, and creates a persistent BO list referencing all five BOs.
    Param render_node: Absolute path to the amdgpu DRM render node (e.g. `/dev/dri/renderD128`).
    Returns: A ready `TokenBoundary` on success; the relevant `error.*Failed` variant otherwise.
    Note: Linux-only; returns `error.UnsupportedOs` on other platforms.
  - TokenBoundary.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-deinit
    Signature: pub fn deinit(self: *TokenBoundary) void
    Summary: Tear down every kernel resource the `init*` paths created: destroy the BO list, free the amdgpu context, `munmap` each CPU mapping, and close the render-node file descriptor.
    Note: Leaves the struct in an `undefined` state; do not reuse it.
  - TokenBoundary.copyU32 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-copy-u32
    Signature: pub fn copyU32(self: *TokenBoundary, value: u32) !u32
    Summary: Round-trip one `u32` through the GPU as the simplest end-to-end gate: PM4 `COPY_DATA` from the input page to the output page, plus a `WRITE_DATA` of a per-submission sentinel into the signal page.
    Param value: 32-bit payload to copy.
    Returns: The value the GPU wrote into `output_map[0]`.
    Note: Returns `error.SignalMismatch` if the post-fence signal value does not match the expected sentinel.
  - TokenBoundary.produceToken [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-produce-token
    Signature: pub fn produceToken(self: *TokenBoundary, token_id: u32) !u32
    Summary: Alias for `copyU32` framed as the per-token decode pulse: prove the GPU produced a token by round-tripping its id through a real PM4 submission and fence wait.
    Param token_id: Token id to round-trip through the GPU.
    Returns: The id the GPU echoed back into the output page.
  - TokenBoundary.argmaxTop2 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-argmax-top2
    Signature: pub fn argmaxTop2( self: *TokenBoundary, token0: u32, score0: f32, token1: u32, score1: f32, ) !u32
    Summary: Dispatch the gfx1201 top-2 argmax kernel and return the selected token.
    Description: Loads the argmax program into the compute SGPRs, packs the output VA, two ordered scores, and two token ids into `compute_user_data_2..7`, fires one workgroup, then waits on the signal sentinel before reading the kernel-chosen token from the output page.
    Param token0: First candidate token id.
    Param score0: Logit/score for `token0` (compared via ordered f32 bits).
    Param token1: Second candidate token id.
    Param score1: Logit/score for `token1`.
    Returns: Whichever of `token0`/`token1` the kernel selected.
    Note: Returns `error.SignalMismatch` on fence mismatch or `error.ArgmaxTop2InvalidToken` if the kernel writes anything else.
  - TokenBoundary.argmaxF32Range [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-argmax-f32-range
    Signature: pub fn argmaxF32Range( self: *TokenBoundary, scores: []const f32, start_row: u32, ) !ArgmaxRangeResult
    Summary: Dispatch the gfx1201 ordered-score row-range argmax kernel.
    Description: Converts `scores` into sortable u32 keys, copies them into the shared input page, then lets the compute ring select the max row. The returned token id is absolute: `start_row + local_best`.
    Param scores: F32 logit/score row range to select from.
    Param start_row: Absolute token row corresponding to `scores[0]`.
    Returns: The selected absolute token id and the ordered score key the GPU stored.
  - TokenBoundary.rmsNormElement0 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-rms-norm-element0
    Signature: pub fn rmsNormElement0( self: *TokenBoundary, hidden0: f32, inv_rms: f32, weight0: f32, ) !f32
    Summary: Dispatch the single-element gfx1201 final-RMS-norm kernel.
    Description: Stores `hidden0 * inv_rms * weight0` into `output_map[0]` via a real PM4 dispatch on the compute ring, with a signal sentinel verifying retirement.
    Param hidden0: First hidden-state element.
    Param inv_rms: Pre-computed inverse RMS scale.
    Param weight0: First RMS-norm weight.
    Returns: The fused `hidden0 * inv_rms * weight0` value the GPU produced.
    Note: Returns `error.SignalMismatch` if the signal sentinel does not match the expected per-submission value.
  - TokenBoundary.dmmvF32RowRange [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-dmmv-f32-row-range
    Signature: pub fn dmmvF32RowRange( self: *TokenBoundary, input: []const f32, weights_f32: []const u8, rows: u32, cols: u32, output: []f32, ) !void
    Summary: Dispatch the gfx1201 row-range f32 dense matrix-vector kernel.
    Description: Copies the input vector and the row-major f32 weight block into the shared input page (64-byte aligned), records PM4 that points the kernel at the input/weights/output pages and the `rows`/`cols` arguments, and waits on the signal sentinel before reading `output`. This is the first row-oriented dense compute kernel the CS path runs; `cols` must be a multiple of 64 and `output` must hold at least `rows` elements.
    Param input: Input activation vector of length `cols`.
    Param weights_f32: Row-major weight bytes; must hold at least `rows*cols*4` bytes.
    Param rows: Number of output rows to compute.
    Param cols: Inner dimension; must be a multiple of 64.
    Param output: Output slice receiving `rows` f32 values.
    Note: Returns `error.ShapeMismatch`, `error.InputTooLarge`, `error.OutputTooLarge`, or `error.SignalMismatch` on invalid shapes or signal-readback failure.
  - TokenBoundary.dmmvF32TwoRowRanges [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-dmmv-f32-two-row-ranges
    Signature: pub fn dmmvF32TwoRowRanges( self: *TokenBoundary, input: []const f32, weights_a_f32: []const u8, rows_a: u32, weights_b_f32: []const u8, rows_b: u32, cols: u32, output: []f32, ) !void
    Summary: Dispatch one F32 DMMV kernel over two packed row ranges sharing the same input vector.
    Description: This is used by the M1 SSM bridge to consume alpha and beta projection rows in one CS submission when both tensors are F32. The existing row-range shader sees one compact `rows_a + rows_b` matrix; output rows are written in that same order.
  - TokenBoundary.dmmvQ4_0RowRange [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-dmmv-q4-0-row-range
    Signature: pub fn dmmvQ4_0RowRange( self: *TokenBoundary, input: []const f32, weights_q4_0: []const u8, rows: u32, cols: u32, output: []f32, ) !void
    Summary: Dispatch the gfx1201 row-range Q4_0 matrix-vector kernel.
    Description: Copies the input vector and raw GGML Q4_0 rows into the shared input page, records PM4 for one serial workitem over `rows`, and reads back one f32 result per row. This intentionally validates real quantized model bytes through the native CS path while the full K-parallel DMMV kernel is still under construction.
    Param input: Input activation vector of length `cols`.
    Param weights_q4_0: Row-major GGML Q4_0 row bytes; must hold at least `rows * (cols/32*18)` bytes.
    Param rows: Number of output rows to compute.
    Param cols: Inner dimension; must be a multiple of 32.
    Param output: Output slice receiving `rows` f32 values.
  - TokenBoundary.dmmvQ4_0RowRangeParallel [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-dmmv-q4-0-row-range-parallel
    Signature: pub fn dmmvQ4_0RowRangeParallel( self: *TokenBoundary, input: []const f32, weights_q4_0: []const u8, rows: u32, cols: u32, output: []f32, ) !void
    Summary: Dispatch the wave-lane gfx1201 Q4_0 matrix-vector kernel for exactly 64 rows in parallel.
    Description: Stages the same source-format rows as `dmmvQ4_0RowRange`, but launches one wave64 workgroup where each lane computes one row. Intended for 64-row LM-head prefix/window ranges where the GPU row values participate in choosing the sampled token.
    Param input: Input activation vector of length `cols`.
    Param weights_q4_0: Row-major GGML Q4_0 row bytes; must hold exactly 64 rows.
    Param rows: Must be exactly 64; any other value returns `error.ShapeMismatch`.
    Param cols: Inner dimension; must be a multiple of 32.
    Param output: Output slice receiving 64 f32 values (one per row).
    Note: Returns `error.SignalMismatch` if the post-fence signal value does not match the expected sentinel.
  - TokenBoundary.sgprTgidProbe [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-sgpr-tgid-probe
    Signature: pub fn sgprTgidProbe(self: *TokenBoundary, groups: u32, out: []u32) !void
    Summary: Dispatch the multi-workgroup TGID-delivery probe: `groups` workgroups, one workitem each, each storing its `workgroup_id_x` (SGPR s8) at `out[workgroup_id_x]`.
    Description: A correct dispatch yields `out[0..groups] = [0,1,...,groups-1]`; if TGID is not delivered, every workgroup collides at `out[0]`. Validates the grid-over-rows premise of the resident DMMV.
  - TokenBoundary.sgprTgidDump [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-sgpr-tgid-dump
    Signature: pub fn sgprTgidDump(self: *TokenBoundary, groups: u32, out: []u32) !void
    Summary: Dispatch the exhaustive TGID-slot probe (`tgid_dump`): `groups` workgroups scan candidate SGPRs s8..s19 and store each candidate value via a value-as-index trick.
    Description: Fills `out[0..out.len]` from the output BO; the caller decodes which candidate slot reads [0,1,...] across workgroups. `out[960]` reads 0x53475052 ("SGPR") iff the kernel ran.
  - TokenBoundary.dmmvQ4_0ResidentGrid [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-dmmv-q4-0-resident-grid
    Signature: pub fn dmmvQ4_0ResidentGrid( self: *TokenBoundary, input: []const f32, weights_q4_0: []const u8, rows: u32, cols: u32, output: []f32, ) !void
    Summary: Grid-over-rows Q4_0 dequant-matvec.
    Description: Stages `input` + `weights_q4_0` into the input BO, dispatches ceil(rows/64) workgroups (each picks its 64-row block from workgroup_id_x/ttmp9), and reads back `rows` results in ONE submit. This is the correctness path (weights staged per call); the perf path will instead point s[4:5] at a VRAM-resident weight BO.
  - TokenBoundary.probeVramMappable [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-probe-vram-mappable
    Signature: pub fn probeVramMappable(self: *TokenBoundary, size: usize) !bool
    Summary: One-shot check that a `size`-byte VRAM BO is CPU-mappable (large-BAR) and round-trips a host write/read.
    Description: Gates the resident-weight LM-head matvec, which only beats the CPU if the weight lives in VRAM (576 GB/s) rather than GTT (PCIe-bound). Leaks the probe BO (reclaimed at process exit).
  - TokenBoundary.dmmvQ4_0RowPartial64 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-dmmv-q4-0-row-partial64
    Signature: pub fn dmmvQ4_0RowPartial64( self: *TokenBoundary, input: []const f32, row_q4_0: []const u8, cols: u32, partials_out: ?[]f32, ) !f32
    Summary: Dispatch the wave64 Q4_0 single-row partial-sum kernel and reduce it on the host.
    Description: This lowers one real model row through a K-parallel CS kernel: lanes 0..31 each accumulate one column per Q4_0 block, the kernel writes 64 partial sums, and the host performs the final scalar reduction. The caller may pass `partials_out` to inspect the raw lane outputs.
    Param input: Input activation vector of length `cols`.
    Param row_q4_0: Raw GGML Q4_0 bytes for one row; must hold `(cols/32)*18` bytes.
    Param cols: Inner dimension; must be a multiple of 32.
    Param partials_out: Optional output slice receiving 64 f32 partial sums.
    Returns: Reduced dot-product score.
  - TokenBoundary.dmmvQ4_0RowRangeParallelChunks [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-dmmv-q4-0-row-range-parallel-chunks
    Signature: pub fn dmmvQ4_0RowRangeParallelChunks( self: *TokenBoundary, input: []const f32, weights_q4_0: []const u8, rows: u32, cols: u32, output: []f32, ) !void
    Summary: Dispatch one or more 64-row wave-lane Q4_0 DMMV chunks in a single CS submission.
    Description: Each chunk runs the same source-format row-parallel shader as `dmmvQ4_0RowRangeParallel`; this helper stages a larger adjacent row window, emits one dispatch per 64-row chunk into the same IB, and waits once after the final release fence. The output slice receives all rows in order.
    Param input: Input activation vector of length `cols`.
    Param weights_q4_0: Row-major GGML Q4_0 row bytes; must hold `rows` rows.
    Param rows: Number of rows to compute; must be a positive multiple of 64.
    Param cols: Inner dimension; must be a multiple of 32.
    Param output: Output slice receiving `rows` f32 values.
  - TokenBoundary.stageDmmvQ4_0RowsResident [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-stage-dmmv-q4-0-rows-resident
    Signature: pub fn stageDmmvQ4_0RowsResident( self: *TokenBoundary, weights_q4_0: []const u8, rows: u32, cols: u32, ) !ResidentDmmvQ4_0Rows
    Summary: Stage a Q4_0 row window into the high end of the long-lived input BO.
    Description: The returned handle is valid until another caller overwrites the same resident region. Default M1 generation uses it for the first LM-head prefix proof, before any broad validation slices can reuse the scratch.
  - TokenBoundary.beginDmmvQ4_0RowRangeParallelChunksResident [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-begin-dmmv-q4-0-row-range-parallel-chunks-resident
    Signature: pub fn beginDmmvQ4_0RowRangeParallelChunksResident( self: *TokenBoundary, input: []const f32, resident: ResidentDmmvQ4_0Rows, ) !PendingDmmvQ4_0RowRangeParallelChunks
    Summary: Dispatch a previously staged resident Q4_0 row window.
    Description: Only the activation vector is copied for this submission; PM4 points the shader at the resident weight VA in the shared input BO.
  - TokenBoundary.beginDmmvQ4_0RowRangeParallelChunks [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-begin-dmmv-q4-0-row-range-parallel-chunks
    Signature: pub fn beginDmmvQ4_0RowRangeParallelChunks( self: *TokenBoundary, input: []const f32, weights_q4_0: []const u8, rows: u32, cols: u32, ) !PendingDmmvQ4_0RowRangeParallelChunks
    Summary: Submit one or more 64-row wave-lane Q4_0 chunks and return before waiting for the CS fence.
    Description: The shared input/output/signal maps and PM4 builder must not be reused until the returned dispatch is finished.
  - TokenBoundary.dmmvQ4_0TwoRowRangesParallel64 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-dmmv-q4-0-two-row-ranges-parallel64
    Signature: pub fn dmmvQ4_0TwoRowRangesParallel64( self: *TokenBoundary, input: []const f32, weights_a_q4_0: []const u8, weights_b_q4_0: []const u8, cols: u32, output: []f32, ) !void
    Summary: Dispatch two 64-row Q4_0 DMMV ranges that share one input vector in one CS submission.
    Description: The two ranges are staged back-to-back, then the existing 64-lane Q4_0 row-parallel kernel is dispatched twice in the same IB. The output slice receives A's 64 rows first and B's 64 rows second. This is used by the M1 forward bridge to consume a wider routed MoE gate/up slice without adding a second fence wait.
    Param input: Input activation vector of length `cols`.
    Param weights_a_q4_0: Row-major GGML Q4_0 bytes for range A; must hold exactly 64 rows.
    Param weights_b_q4_0: Row-major GGML Q4_0 bytes for range B; must hold exactly 64 rows.
    Param cols: Inner dimension; must be a multiple of 32.
    Param output: Output slice receiving 128 f32 values: A rows first, then B rows.
  - TokenBoundary.dmmvQ4_0FourRowRangesParallel64 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-dmmv-q4-0-four-row-ranges-parallel64
    Signature: pub fn dmmvQ4_0FourRowRangesParallel64( self: *TokenBoundary, input: []const f32, weights_a_q4_0: []const u8, weights_b_q4_0: []const u8, weights_c_q4_0: []const u8, weights_d_q4_0: []const u8, cols: u32, output: []f32, ) !void
    Summary: Dispatch four 64-row Q4_0 DMMV ranges that share one input vector in one CS submission.
    Description: This is the batched companion to `dmmvQ4_0TwoRowRangesParallel64` for decode-phase MoE gate/up validation across two routed experts. The output slice receives A, B, C, D ranges in order.
  - TokenBoundary.dmmvQ4_0TwoRows [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-dmmv-q4-0-two-rows
    Signature: pub fn dmmvQ4_0TwoRows( self: *TokenBoundary, input: []const f32, row_a_q4_0: []const u8, row_b_q4_0: []const u8, cols: u32, output: []f32, ) !void
    Summary: Dispatch Q4_0 DMMV for two arbitrary model rows staged back-to-back.
    Description: The caller supplies two individual source-format rows, which are packed into the shared staging page as a compact two-row matrix. This lets the current forward path obtain both LM-head top-2 scores from one real DMMV row-range submission even when the rows are not adjacent in vocab.
    Param input: Input activation vector of length `cols`.
    Param row_a_q4_0: Raw GGML Q4_0 bytes for the first row; must hold at least `(cols/32)*18` bytes.
    Param row_b_q4_0: Raw GGML Q4_0 bytes for the second row; same size requirement as `row_a_q4_0`.
    Param cols: Inner dimension; must be a multiple of 32.
    Param output: Output slice receiving 2 f32 values: `output[0]` for row A, `output[1]` for row B.
    Note: Returns `error.SignalMismatch` if the post-fence signal sentinel does not match.
  - TokenBoundary.dmmvQ4_0ArgmaxRowRange [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-dmmv-q4-0-argmax-row-range
    Signature: pub fn dmmvQ4_0ArgmaxRowRange( self: *TokenBoundary, input: []const f32, weights_q4_0: []const u8, rows: u32, cols: u32, ) !DmmvArgmaxResult
    Summary: Dispatch the gfx1201 Q4_0 row-range DMMV kernel that performs argmax in the same submission.
    Description: The method stages the exact same source-format input and Q4_0 rows as `dmmvQ4_0RowRange`, but the kernel only stores the local best row and score. The forward path uses this for LM-head prefix/window candidates so a GPU-produced model value can directly participate in sampling without a follow-up direct argmax dispatch over copied logits.
  - TokenBoundary.dmmvQ8_0RowRange [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-dmmv-q8-0-row-range
    Signature: pub fn dmmvQ8_0RowRange( self: *TokenBoundary, input: []const f32, weights_q8_0: []const u8, rows: u32, cols: u32, output: []f32, ) !void
    Summary: Dispatch the gfx1201 row-range Q8_0 matrix-vector kernel.
    Description: Copies the input vector and raw GGML Q8_0 rows into the shared input page, records PM4 for one serial workitem over `rows`, and reads back one f32 result per row. This keeps source-format Q8_0 model-slice validation exact while the final K-parallel DMMV kernel is still under construction.
    Param input: Input activation vector of length `cols`.
    Param weights_q8_0: Row-major GGML Q8_0 row bytes; must hold at least `rows * (cols/32*34)` bytes.
    Param rows: Number of output rows to compute.
    Param cols: Inner dimension; must be a multiple of 32.
    Param output: Output slice receiving `rows` f32 values.
  - TokenBoundary.dmmvQ8_0TwoRowRanges [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-dmmv-q8-0-two-row-ranges
    Signature: pub fn dmmvQ8_0TwoRowRanges( self: *TokenBoundary, input: []const f32, weights_a_q8_0: []const u8, rows_a: u32, weights_b_q8_0: []const u8, rows_b: u32, cols: u32, output: []f32, ) !void
    Summary: Dispatch one gfx1201 Q8_0 DMMV kernel over two adjacent logical row ranges that share the same input vector.
    Description: The method packs `weights_a` followed by `weights_b` into the staging page, then runs the same compact Q8_0 row-range kernel over `rows_a + rows_b` rows. The output slice receives A's rows first and B's rows second. This is used by the M1 bridge to consume paired SSM alpha/beta projections without paying two CS submissions for the same activation vector.
    Param input: Input activation vector of length `cols`.
    Param weights_a_q8_0: Row-major GGML Q8_0 bytes for range A; must hold at least `rows_a * (cols/32*34)` bytes.
    Param rows_a: Number of rows in the A range.
    Param weights_b_q8_0: Row-major GGML Q8_0 bytes for range B; must hold at least `rows_b * (cols/32*34)` bytes.
    Param rows_b: Number of rows in the B range.
    Param cols: Inner dimension; must be a multiple of 32.
    Param output: Output slice receiving `rows_a + rows_b` f32 values: A rows first, then B rows.
    Note: Returns `error.SignalMismatch` if the post-fence signal sentinel does not match.
  - TokenBoundary.dmmvQ8_0TwoRowRangesParallel64 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#token-boundary-dmmv-q8-0-two-row-ranges-parallel64
    Signature: pub fn dmmvQ8_0TwoRowRangesParallel64( self: *TokenBoundary, input: []const f32, weights_a_q8_0: []const u8, rows_a: u32, weights_b_q8_0: []const u8, rows_b: u32, cols: u32, output: []f32, ) !void
    Summary: Dispatch one wave64 Q8_0 DMMV kernel over two packed row ranges totalling exactly 64 rows.
    Description: This is the row-parallel companion to `dmmvQ8_0TwoRowRanges` for the current SSM alpha+beta shape: 32 alpha rows plus 32 beta rows. Each lane computes one row from the packed staging block, eliminating the serial per-row loop of the scalar variant.
    Param input: Input activation vector of length `cols`.
    Param weights_a_q8_0: Row-major GGML Q8_0 bytes for range A; must hold at least `rows_a * (cols/32*34)` bytes.
    Param rows_a: Number of rows in the A range; `rows_a + rows_b` must equal 64.
    Param weights_b_q8_0: Row-major GGML Q8_0 bytes for range B; must hold at least `rows_b * (cols/32*34)` bytes.
    Param rows_b: Number of rows in the B range.
    Param cols: Inner dimension; must be a multiple of 32.
    Param output: Output slice receiving exactly 64 f32 values: A rows first, then B rows.
    Note: Returns `error.ShapeMismatch` if `rows_a + rows_b != 64`. Returns `error.SignalMismatch` on sentinel mismatch.

- lastErrno [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#last-errno
  Signature: pub fn lastErrno() ?linux.E
  Summary: Errno captured from the most recent `ioctl` issued by this module, or null if the call succeeded.
  Description: Useful for surfacing a precise reason after a `SmokeResult.status` indicates a kernel-side failure.
  Returns: The latest captured `linux.E` value, or null when there was no error.

- setupSmokeDefault [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#setup-smoke-default
  Signature: pub fn setupSmokeDefault() SmokeResult
  Summary: Run the bring-up smoke gate against `default_render_node`.
  Returns: A `SmokeResult` summarizing whether the two PM4 submissions retired and the signal sentinel matched.

- setupSmokePath [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#setup-smoke-path
  Signature: pub fn setupSmokePath(render_node: []const u8) SmokeResult
  Summary: Run the bring-up smoke gate against the given DRM render node path.
  Param render_node: Absolute path to the amdgpu DRM render node to test.
  Returns: A `SmokeResult` describing the open → submit → wait outcome.

- submitNopSmokeDefault [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#submit-nop-smoke-default
  Signature: pub fn submitNopSmokeDefault() SmokeResult
  Summary: Backwards-compatible alias for `setupSmokeDefault` named for the underlying PM4 NOP+WRITE_DATA stream that exercises the CS path.
  Returns: A `SmokeResult` describing the bring-up outcome on `default_render_node`.

- submitNopSmokePath [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cs/#submit-nop-smoke-path
  Signature: pub fn submitNopSmokePath(render_node: []const u8) SmokeResult
  Summary: Full bring-up smoke implementation: open the render node, query compute IP, allocate a context, create GTT-backed IB + signal BOs and map them at fixed low GPU VAs, build a PM4 NOP + `WRITE_DATA` stream, submit it twice through `DRM_IOCTL_AMDGPU_CS`, and verify each fence retires with the expected signal sentinel in the signal BO.
  Param render_node: Absolute path to the amdgpu DRM render node to exercise.
  Returns: A `SmokeResult` whose `status` pinpoints the failure stage, or `.ok` on success.
  Note: Returns `.unsupported_os` immediately on non-Linux hosts; never throws.

### Module: Kfd
URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/
Source: src/zinc_rt/ring/kfd.zig
Code lines: 731
Summary: AMDGPU KFD (`/dev/kfd`) bring-up for the T1 PM4-direct tier.
Overview: The design's T1 tier submits PM4 packets straight to the AMD command processor. On Linux that means the KFD compute path (`/dev/kfd` + `AMDKFD_IOC_*`), the same userspace ABI ROCm/HSA and tinygrad ride on. It works on every `amdgpu` kernel that ships KFD and does not depend on the experimental user-mode-queue (UMQ / `DRM_IOCTL_AMDGPU_USERQ`) ABI, which on the R9700 (gfx1201, kernel 6.17, `uni_mes` firmware) the kernel rejects with "Usermode queue is not supported for this IP" — see `umq.zig` and §14 of the design doc.
Overview: This module brings up the T1 PM4-direct path on the kernel ABI that works: * open `/dev/kfd` + the render node, `AMDKFD_IOC_GET_VERSION`, * match the render minor against `/sys/.../kfd/topology/nodes/*`, * `AMDKFD_IOC_ACQUIRE_VM`, `AMDKFD_IOC_GET_PROCESS_APERTURES_NEW`, * `bringUpPath`: reserve a VA window inside the GPUVM aperture, `ALLOC_MEMORY_OF_GPU` (GTT, writable) + `mmap` + `MAP_MEMORY_TO_GPU` + a CPU round-trip, then `UNMAP_MEMORY_FROM_GPU` + `FREE_MEMORY_OF_GPU`, * `createComputeQueueSmokePath`: allocate the ring / wptr / rptr / EOP / CWSR buffer objects the way `kfd_queue_acquire_buffers` validates them, `AMDKFD_IOC_CREATE_QUEUE` (PM4 compute), stage a couple of PM4 NOP packets into the ring, then `AMDKFD_IOC_DESTROY_QUEUE` and tear down. Ringing the doorbell and retiring a PM4 fence is the next bring-up step.

- default_render_node [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#default-render-node
  Signature: pub const default_render_node = "/dev/dri/renderD128"
  Summary: Default DRM render node used when the caller does not supply one.
  Description: The renderD128 minor is the standard single-GPU choice on AMD Linux systems.

- kfd_device_node [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#kfd-device-node
  Signature: pub const kfd_device_node = "/dev/kfd"
  Summary: Path to the KFD compute device used for every AMDKFD_IOC_* ioctl.

- topology_nodes_dir [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#topology-nodes-dir
  Signature: pub const topology_nodes_dir = "/sys/devices/virtual/kfd/kfd/topology/nodes"
  Summary: Sysfs root that enumerates KFD topology nodes (one subdirectory per node, each carrying `gpu_id` and a `properties` file that drives queue sizing).

- min_kfd_major [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#min-kfd-major
  Signature: pub const min_kfd_major: u32 = 1
  Summary: Minimum KFD ABI major version required for the PM4 compute path; the bring-up fails fast with `kfd_version_too_old` below this number.

- ALLOC_MEM_FLAGS_VRAM [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#alloc-mem-flags-vram
  Signature: pub const ALLOC_MEM_FLAGS_VRAM: u32 = 1 << 0
  Summary: Allocate the BO out of device VRAM (local frame buffer).

- ALLOC_MEM_FLAGS_GTT [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#alloc-mem-flags-gtt
  Signature: pub const ALLOC_MEM_FLAGS_GTT: u32 = 1 << 1
  Summary: Allocate the BO out of system GTT memory (the path used by every smoke BO).

- ALLOC_MEM_FLAGS_USERPTR [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#alloc-mem-flags-userptr
  Signature: pub const ALLOC_MEM_FLAGS_USERPTR: u32 = 1 << 2
  Summary: Pin a userptr range as the BO backing; not used by the bring-up smoke path.

- ALLOC_MEM_FLAGS_DOORBELL [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#alloc-mem-flags-doorbell
  Signature: pub const ALLOC_MEM_FLAGS_DOORBELL: u32 = 1 << 3
  Summary: Allocate a doorbell page so a userspace queue can ring its wptr doorbell.

- ALLOC_MEM_FLAGS_COHERENT [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#alloc-mem-flags-coherent
  Signature: pub const ALLOC_MEM_FLAGS_COHERENT: u32 = 1 << 26
  Summary: Request a CPU-coherent BO (snooped on x86); not used by the bring-up smoke path.

- ALLOC_MEM_FLAGS_PUBLIC [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#alloc-mem-flags-public
  Signature: pub const ALLOC_MEM_FLAGS_PUBLIC: u32 = 1 << 29
  Summary: Mark the BO as PCIe-visible / exportable to peer devices.

- ALLOC_MEM_FLAGS_EXECUTABLE [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#alloc-mem-flags-executable
  Signature: pub const ALLOC_MEM_FLAGS_EXECUTABLE: u32 = 1 << 30
  Summary: Mark the BO as containing GPU-executable code (shader binaries).

- ALLOC_MEM_FLAGS_WRITABLE [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#alloc-mem-flags-writable
  Signature: pub const ALLOC_MEM_FLAGS_WRITABLE: u32 = 1 << 31
  Summary: Map the BO with write permission on the GPU side (default for smoke BOs).

- QUEUE_TYPE_COMPUTE [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#queue-type-compute
  Signature: pub const QUEUE_TYPE_COMPUTE: u32 = 0x0
  Summary: PM4 compute queue type passed to `AMDKFD_IOC_CREATE_QUEUE` for MEC pipes.

- QUEUE_TYPE_SDMA [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#queue-type-sdma
  Signature: pub const QUEUE_TYPE_SDMA: u32 = 0x1
  Summary: SDMA queue type; copy engine queue, not used by the PM4 compute bring-up.

- QUEUE_TYPE_COMPUTE_AQL [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#queue-type-compute-aql
  Signature: pub const QUEUE_TYPE_COMPUTE_AQL: u32 = 0x2
  Summary: AQL compute queue type (HSA packet processor format) used by ROCm/HSA.

- GetVersionArgs [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#get-version-args
  Signature: pub const GetVersionArgs = extern struct
  Summary: `AMDKFD_IOC_GET_VERSION` ioctl args — the KFD ABI version reported by the running kernel.
  Description: Matches `struct kfd_ioctl_get_version_args` from uapi.

- AcquireVmArgs [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#acquire-vm-args
  Signature: pub const AcquireVmArgs = extern struct
  Summary: `AMDKFD_IOC_ACQUIRE_VM` ioctl args — binds the calling process's GPUVM to the DRM render node fd so subsequent allocations land in the right address space.

- ProcessDeviceApertures [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#process-device-apertures
  Signature: pub const ProcessDeviceApertures = extern struct
  Summary: One device aperture entry returned by `GET_PROCESS_APERTURES_NEW`: the LDS, scratch, and GPUVM windows that this process is allowed to use on the indicated `gpu_id`.
  Description: The bring-up only consumes `gpuvm_base/limit`.

- GetProcessAperturesNewArgs [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#get-process-apertures-new-args
  Signature: pub const GetProcessAperturesNewArgs = extern struct
  Summary: `AMDKFD_IOC_GET_PROCESS_APERTURES_NEW` ioctl args — caller supplies a pointer to an array of `ProcessDeviceApertures` plus its length; the kernel fills the array and updates `num_of_nodes` with the actual count.

- AllocMemoryOfGpuArgs [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#alloc-memory-of-gpu-args
  Signature: pub const AllocMemoryOfGpuArgs = extern struct
  Summary: `AMDKFD_IOC_ALLOC_MEMORY_OF_GPU` ioctl args.
  Description: The caller chooses the GPU VA (`va_addr`) and the kernel returns a BO `handle` plus an `mmap_offset` for the DRM render node so the BO can be CPU-mapped.

- FreeMemoryOfGpuArgs [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#free-memory-of-gpu-args
  Signature: pub const FreeMemoryOfGpuArgs = extern struct
  Summary: `AMDKFD_IOC_FREE_MEMORY_OF_GPU` ioctl args — release the BO referenced by `handle` (must already be unmapped from every GPU it was mapped to).

- MapMemoryToGpuArgs [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#map-memory-to-gpu-args
  Signature: pub const MapMemoryToGpuArgs = extern struct
  Summary: `AMDKFD_IOC_MAP_MEMORY_TO_GPU` / `UNMAP_MEMORY_FROM_GPU` ioctl args.
  Description: Same layout for both directions; the kernel updates `n_success` with the number of devices the BO was successfully (un)mapped on.

- CreateQueueArgs [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#create-queue-args
  Signature: pub const CreateQueueArgs = extern struct
  Summary: `AMDKFD_IOC_CREATE_QUEUE` ioctl args — describes the PM4 compute queue the kernel should map onto the MEC.
  Description: Every BO address (ring/wptr/rptr/EOP/CWSR) must already be allocated and mapped to the same GPU before the ioctl.

- DestroyQueueArgs [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#destroy-queue-args
  Signature: pub const DestroyQueueArgs = extern struct
  Summary: `AMDKFD_IOC_DESTROY_QUEUE` ioctl args — release the queue identified by `queue_id` (the value the kernel returned from `CREATE_QUEUE`).

- TopologyNode [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#topology-node
  Signature: pub const TopologyNode = struct
  Summary: One GPU topology node parsed from `topology_nodes_dir`.
  Description: Carries the values the queue bring-up needs to validate `CREATE_QUEUE`: `gpu_id`, the GFX IP target version, CU/SIMD counts that drive CWSR sizing, and the canonical `cwsr_size` / `ctl_stack_size` advertised by the kernel.

- BringUpStatus [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#bring-up-status
  Signature: pub const BringUpStatus = enum
  Summary: Outcome categories for `bringUpPath`.
  Description: Every non-`ok` value identifies the exact bring-up step that failed (open, version check, aperture lookup, VA reservation, alloc, map, mmap, CPU round-trip, unmap, free).

- BringUpResult [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#bring-up-result
  Signature: pub const BringUpResult = struct
  Summary: Full bring-up report produced by `bringUpPath`.
  Description: Captures the status plus every observable value the smoke run collected (KFD ABI version, topology info, the GPUVM window, the reserved VA, and the errno of the last failing ioctl when applicable) so callers can render diagnostics without rerunning.
  - BringUpResult.ok [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#bring-up-result-ok
    Signature: pub fn ok(self: BringUpResult) bool
    Summary: True when every bring-up step succeeded (`status == .ok`).

- lastErrno [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#last-errno
  Signature: pub fn lastErrno() ?linux.E
  Summary: Returns the errno of the most recent failing ioctl, or `null` if the last ioctl succeeded.
  Description: Cleared at the start of each `ioctlChecked` call.

- renderMinorOf [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#render-minor-of
  Signature: pub fn renderMinorOf(render_node: []const u8) ?u32
  Summary: Extract the DRM render minor number from a `/dev/dri/renderD<N>` path.
  Description: contain a recognizable `renderD<digits>` suffix.
  Param render_node: Absolute path to the DRM render node (e.g. `/dev/dri/renderD128`).
  Returns: The parsed minor number (e.g. 128), or `null` if the path does not

- findTopologyNode [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#find-topology-node
  Signature: pub fn findTopologyNode(render_minor: u32) ?TopologyNode
  Summary: Scan `topology_nodes_dir` for the GPU topology node whose `drm_render_minor` matches the given render minor, parsing `gpu_id`, `gfx_target_version`, `simd_count`, `cwsr_size`, and related properties from each node's `properties` file.
  Description: CPU-only nodes (gpu_id == 0) are skipped. the sysfs directory cannot be opened.
  Param render_minor: DRM render minor to match (e.g. 128 for `renderD128`).
  Returns: The matching `TopologyNode`, or `null` if no GPU node matches or if
  Note: Always returns `null` on non-Linux targets.

- reachable [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#reachable
  Signature: pub fn reachable() bool
  Summary: Cheaply test whether the KFD PM4 path appears usable on this machine without issuing any ioctls: opens `/dev/kfd`, then verifies that a matching topology node with a non-zero `gpu_id` exists in sysfs for the default render minor.
  Description: found for the default render node; `false` otherwise or on non-Linux targets.
  Returns: `true` when `/dev/kfd` is accessible and a valid topology node is

- bringUpDefault [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#bring-up-default
  Signature: pub fn bringUpDefault() BringUpResult
  Summary: Run `bringUpPath` against `default_render_node` ("/dev/dri/renderD128").
  Returns: Status + diagnostics for the GPUVM round-trip.

- bringUpPath [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#bring-up-path
  Signature: pub fn bringUpPath(render_node: []const u8) BringUpResult
  Summary: End-to-end KFD bring-up: open `/dev/kfd` and the supplied render node, check the ABI version, acquire the GPUVM, look up the matching topology aperture, reserve a 64 KiB VA window inside it, allocate + mmap + MAP_MEMORY_TO_GPU a 4 KiB GTT scratch BO, write/read a magic value to verify the round-trip, then unmap and free everything.
  Description: Every failure point is captured in the returned `BringUpResult` (status + last errno) so a non-Linux caller or a partial-permissions environment can still get a useful diagnostic without panicking. round-trip.
  Param render_node: Path to the DRM render node (e.g. `/dev/dri/renderD128`).
  Returns: A populated `BringUpResult`; `.ok()` is true only on a clean
  Note: Off Linux this short-circuits to `unsupported_os` and performs no IO.

- ComputeQueueSmokeStatus [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#compute-queue-smoke-status
  Signature: pub const ComputeQueueSmokeStatus = enum
  Summary: Outcome categories for the PM4 compute-queue smoke path.
  Description: Each non-`ok` value identifies a specific failure step (BO allocation, map, `CREATE_QUEUE`, `DESTROY_QUEUE`) so callers can render bring-up reports.

- ComputeQueueSmokeResult [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#compute-queue-smoke-result
  Signature: pub const ComputeQueueSmokeResult = struct
  Summary: Full report for the PM4 compute-queue smoke run.
  Description: Captures the status plus every observable value the run produced (BO VAs, queue id, doorbell offset, initial wptr/rptr, number of PM4 NOP dwords staged, and the errno of the last failing ioctl) so a higher-level CLI can render bring-up output.
  - ComputeQueueSmokeResult.ok [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#compute-queue-smoke-result-ok
    Signature: pub fn ok(self: ComputeQueueSmokeResult) bool
    Summary: True when the queue was created, NOPs staged, and the queue destroyed without any ioctl failure.

- alignUp [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#align-up
  Signature: pub fn alignUp(value: u64, alignment: u64) u64
  Summary: Round `value` up to the next multiple of `alignment`.
  Description: Returns `value` unchanged when `alignment` is zero or `value` is already aligned.
  Param value: Number to be rounded up.
  Param alignment: Power-of-two (or any non-zero) boundary to align to.
  Returns: Smallest multiple of `alignment` that is `>= value`.

- computeCwsrBoSize [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#compute-cwsr-bo-size
  Signature: pub fn computeCwsrBoSize( cwsr_size: u32, simd_count: u32, simd_per_cu_in: u32, num_xcc_in: u32, gfx_target_version: u32, ) u64
  Summary: Compute the CWSR buffer-object size that the kernel's `kfd_queue_acquire_buffers` will accept for a given GPU topology.
  Description: The formula is `align_up((cwsr_size + debug_memory_size) * num_xcc, PAGE)`, where for gfx ≥ 10.1.x `debug_memory_size = align_up((simd_count / simd_per_cu / num_xcc) * 32 * 32, 64)` and for older IPs `debug_memory_size = 0`. Verified on the R9700 (gfx1201): cwsr_size 0x1d47000, debug 0x10000, resulting BO 0x1d57000. (2 for RDNA, 4 for GCN/CDNA).
  Param cwsr_size: Raw `cwsr_size` from the topology `properties` file (bytes).
  Param simd_count: Total SIMD units across all XCCs for this GPU.
  Param simd_per_cu_in: SIMD units per CU; if 0, derived from `gfx_target_version`
  Param num_xcc_in: Number of XCC dies; treated as 1 if 0.
  Param gfx_target_version: Encoded GFX IP version (major×10000 + minor×100 + step).
  Returns: Total BO allocation size in bytes, page-aligned.

- createComputeQueueSmokeDefault [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#create-compute-queue-smoke-default
  Signature: pub fn createComputeQueueSmokeDefault() ComputeQueueSmokeResult
  Summary: Run `createComputeQueueSmokePath` against `default_render_node`.
  Returns: The compute-queue smoke result; `.ok()` is true on a clean run.

- createComputeQueueSmokePath [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#create-compute-queue-smoke-path
  Signature: pub fn createComputeQueueSmokePath(render_node: []const u8) ComputeQueueSmokeResult
  Summary: Stand up a PM4 compute queue end-to-end on the given render node.
  Description: Allocates the ring / wptr / rptr / EOP / CWSR buffer objects with the sizing rules `kfd_queue_acquire_buffers` validates, calls `AMDKFD_IOC_CREATE_QUEUE`, stages a couple of PM4 NOP packets into the ring (no doorbell yet), then destroys the queue and tears everything down. Every BO and ioctl failure is captured in the returned report so the bring-up smoke test can render the exact step that failed.
  Param render_node: DRM render node backing the target GPU.
  Returns: The full smoke report; `.ok()` is true on a clean create/destroy.
  Note: Off Linux this short-circuits to `unsupported_os` without IO.

- formatGfxTarget [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kfd/#format-gfx-target
  Signature: pub fn formatGfxTarget(buf: []u8, gfx_target_version: u32) []const u8
  Summary: Format a `gfx_target_version` integer (e.g.
  Description: 120001) as a GFX target string such as `"gfx1201"`. The encoding is major×10000 + minor×100 + step, matching the value read from the KFD topology `properties` file. `gfx_target_version` is 0 or the buffer is too small.
  Param buf: Caller-supplied scratch buffer; 16 bytes is sufficient.
  Param gfx_target_version: Encoded GFX IP version, or 0 for an unknown target.
  Returns: A slice into `buf` holding the rendered string, or `"gfx?"` when

### Module: Mod
URL: https://zolotukhin.ai/zinc/docs/zig-api/mod/
Source: src/zinc_rt/ring/mod.zig
Code lines: 16
Summary: Backend-neutral packet batch types for ZINC_RT rings.
Overview: These packet structs are the handoff point between lowered IR and concrete ring implementations such as T-CPU, T2 UMQ, and future direct tiers.

- Packet [union]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/mod/#packet
  Signature: pub const Packet = union(enum)
  Summary: Tagged union describing one unit of work submitted to a ZINC_RT ring.
  Description: Each variant carries the CPU ISA parameter struct that fully describes a single decode-step kernel; the `barrier` variant marks an in-stream ordering point with no shader payload.

- PacketBatch [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/mod/#packet-batch
  Signature: pub const PacketBatch = struct
  Summary: Borrowed slice of packets that form one submission to a ring.
  Description: Ring implementations consume a batch in order, treating `.barrier` entries as completion fences between adjacent dispatches.

### Module: Packet List
URL: https://zolotukhin.ai/zinc/docs/zig-api/packet-list/
Source: src/zinc_rt/ring/packet_list.zig
Code lines: 31
Summary: Dynamic packet list for building per-token decode sequences.
Overview: T-CPU forward passes use this to accumulate packets before submitting them to the CPU ring for execution.

- PacketList [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/packet-list/#packet-list
  Signature: pub const PacketList = struct
  Summary: Growable buffer used to assemble a `PacketBatch` for one decode step.
  Description: Lowering code pushes packets in execution order, interleaves explicit `barrier` entries between dependent dispatches, and then publishes the resulting slice via `slice()` to whichever ring will run the batch.
  - PacketList.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/packet-list/#packet-list-init
    Signature: pub fn init(allocator: std.mem.Allocator) PacketList
    Summary: Create an empty list bound to the given allocator.
    Description: outlive the list.
    Param allocator: Owner of the underlying ArrayList storage; must
    Returns: A `PacketList` with zero packets queued.
  - PacketList.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/packet-list/#packet-list-deinit
    Signature: pub fn deinit(self: *PacketList) void
    Summary: Release the backing storage and poison `self` for use-after-free debug.
    Param self: List to tear down; must not be reused afterwards.
  - PacketList.append [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/packet-list/#packet-list-append
    Signature: pub fn append(self: *PacketList, packet: ring.Packet) !void
    Summary: Push a payload-bearing packet (embed, rms_norm, lm_head, etc.) onto the end of the list.
    Param self: List receiving the packet.
    Param packet: Fully populated packet to enqueue; the value is copied.
  - PacketList.appendBarrier [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/packet-list/#packet-list-append-barrier
    Signature: pub fn appendBarrier(self: *PacketList) !void
    Summary: Append a `.barrier` marker that forces the ring to drain prior packets before continuing.
    Description: buffer (for example, between attention output and the next RMSNorm).
    Param self: List receiving the barrier.
    Note: Used between producer/consumer kernels that share a tensor
  - PacketList.slice [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/packet-list/#packet-list-slice
    Signature: pub fn slice(self: *const PacketList) []const ring.Packet
    Summary: Borrowed view of the current packet sequence.
    Param self: List to inspect.
    Returns: A slice that stays valid until the next mutation of the list.
  - PacketList.len [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/packet-list/#packet-list-len
    Signature: pub fn len(self: *const PacketList) usize
    Summary: Number of packets currently queued, including any barriers.
    Param self: List to inspect.
    Returns: Packet count.
  - PacketList.clear [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/packet-list/#packet-list-clear
    Signature: pub fn clear(self: *PacketList) void
    Summary: Drop all queued packets while keeping the allocated capacity, so the list can be reused for the next decode step without re-allocating.
    Param self: List to reset.

### Module: Packet
URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/
Source: src/zinc_rt/ring/packet.zig
Code lines: 237
Summary: PM4 packet builder shared by direct AMD ZINC_RT tiers.
Overview: This is intentionally syntax-only: it does not know about model shapes or IR op semantics. M1 lowering hands already-decided register writes and dispatch dimensions to this builder, then T2/T1 copy the resulting dwords into their user queue rings.

- Error [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/#error
  Signature: pub const Error = error{OutOfSpace}
  Summary: Failure modes returned by `PacketBuilder` operations.
  Description: `OutOfSpace` means the caller-provided dword buffer cannot fit another PM4 packet without overrunning its bounds.

- sh_reg_num_thread_x [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/#sh-reg-num-thread-x
  Signature: pub const sh_reg_num_thread_x: u32 = 0x207
  Summary: SH register offset for `COMPUTE_NUM_THREAD_X` (workgroup X dimension).

- sh_reg_pgm_lo [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/#sh-reg-pgm-lo
  Signature: pub const sh_reg_pgm_lo: u32 = 0x20c
  Summary: SH register offset for `COMPUTE_PGM_LO` (low 32 bits of the shader address).

- sh_reg_pgm_rsrc1 [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/#sh-reg-pgm-rsrc1
  Signature: pub const sh_reg_pgm_rsrc1: u32 = 0x212
  Summary: SH register offset for `COMPUTE_PGM_RSRC1` (VGPR/SGPR counts and float mode).

- sh_reg_resource_limits [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/#sh-reg-resource-limits
  Signature: pub const sh_reg_resource_limits: u32 = 0x215
  Summary: SH register offset for `COMPUTE_RESOURCE_LIMITS` (waves-per-CU and locking).

- sh_reg_pgm_rsrc3 [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/#sh-reg-pgm-rsrc3
  Signature: pub const sh_reg_pgm_rsrc3: u32 = 0x228
  Summary: SH register offset for `COMPUTE_PGM_RSRC3` (extra GFX11+ shader resource bits).

- compute_user_data_0 [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/#compute-user-data-0
  Signature: pub const compute_user_data_0: u32 = 0x240
  Summary: SH register offset for `COMPUTE_USER_DATA_0`; subsequent slots are contiguous and used to pass kernel argument pointers.

- dispatch_initiator_compute [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/#dispatch-initiator-compute
  Signature: pub const dispatch_initiator_compute: u32 = 5
  Summary: Default `DISPATCH_INITIATOR` value enabling the compute pipeline.

- PacketBuilder [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/#packet-builder
  Signature: pub const PacketBuilder = struct
  Summary: Cursor-style writer that emits PM4 type-3 packets into a caller-owned dword buffer.
  Description: The builder is allocation-free and stateless beyond a write cursor, so callers can reuse the same backing buffer across submissions by calling `reset`.
  - PacketBuilder.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/#packet-builder-init
    Signature: pub fn init(words: []u32) PacketBuilder
    Summary: Wrap a pre-allocated dword buffer.
    Description: index 0 and never grows the slice.
    Param words: Backing storage; the builder writes packets starting at
    Returns: A builder pointing at `words` with an empty write cursor.
  - PacketBuilder.reset [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/#packet-builder-reset
    Signature: pub fn reset(self: *PacketBuilder) void
    Summary: Rewind the write cursor without touching the backing buffer.
    Param self: Builder to reset; subsequent writes overwrite previous dwords.
  - PacketBuilder.written [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/#packet-builder-written
    Signature: pub fn written(self: *const PacketBuilder) []const u32
    Summary: Borrowed view of the dwords emitted so far.
    Param self: Builder to inspect.
    Returns: Slice of finalized packet words, ready to copy into a ring.
  - PacketBuilder.writeNop [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/#packet-builder-write-nop
    Signature: pub fn writeNop(self: *PacketBuilder, payload_dwords: u32) Error!void
    Summary: Emit a PM4 `NOP` packet that consumes `payload_dwords` body dwords.
    Description: minimum of 1 to satisfy the PKT3 body-size encoding.
    Param self: Builder to append to.
    Param payload_dwords: Number of zero payload dwords; clamped to a
  - PacketBuilder.setShReg [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/#packet-builder-set-sh-reg
    Signature: pub fn setShReg(self: *PacketBuilder, reg_offset: u32, values: []const u32) Error!void
    Summary: Emit `SET_SH_REG` writing `values` into consecutive SH register slots.
    Param self: Builder to append to.
    Param reg_offset: Starting SH register offset (dword units from 0xB000).
    Param values: Register values written in order; an empty slice is a no-op.
  - PacketBuilder.setShRegOne [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/#packet-builder-set-sh-reg-one
    Signature: pub fn setShRegOne(self: *PacketBuilder, reg_offset: u32, value: u32) Error!void
    Summary: Convenience helper that writes a single SH register.
    Param self: Builder to append to.
    Param reg_offset: SH register offset.
    Param value: Value to write into that register.
  - PacketBuilder.setUserData64 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/#packet-builder-set-user-data64
    Signature: pub fn setUserData64(self: *PacketBuilder, slot: u32, value: u64) Error!void
    Summary: Write a 64-bit value into a pair of contiguous `COMPUTE_USER_DATA_*` slots, little-endian (low dword first).
    Param self: Builder to append to.
    Param slot: Zero-based index added to `compute_user_data_0`.
    Param value: 64-bit kernel argument (typically a GPU virtual address).
  - PacketBuilder.dispatchDirect [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/#packet-builder-dispatch-direct
    Signature: pub fn dispatchDirect(self: *PacketBuilder, dim_x: u32, dim_y: u32, dim_z: u32) Error!void
    Summary: Emit `DISPATCH_DIRECT` with a zero dispatch-initiator field.
    Description: Prefer `dispatchDirectInitiator` when `COMPUTE_DISPATCH_INITIATOR` bits must be set explicitly (e.g. `dispatch_initiator_compute`).
    Param self: Builder to append to.
    Param dim_x: Workgroup count on X.
    Param dim_y: Workgroup count on Y.
    Param dim_z: Workgroup count on Z.
  - PacketBuilder.dispatchDirectInitiator [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/#packet-builder-dispatch-direct-initiator
    Signature: pub fn dispatchDirectInitiator( self: *PacketBuilder, dim_x: u32, dim_y: u32, dim_z: u32, dispatch_initiator: u32, ) Error!void
    Summary: Emit `DISPATCH_DIRECT` with a caller-supplied dispatch initiator value.
    Description: to take the firmware default or use `dispatch_initiator_compute` to force-enable the compute pipeline.
    Param self: Builder to append to.
    Param dim_x: Workgroup count on X.
    Param dim_y: Workgroup count on Y.
    Param dim_z: Workgroup count on Z.
    Param dispatch_initiator: Raw `COMPUTE_DISPATCH_INITIATOR` bits; pass 0
  - PacketBuilder.releaseMemSignal [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/#packet-builder-release-mem-signal
    Signature: pub fn releaseMemSignal(self: *PacketBuilder, gpu_addr: u64, value: u64) Error!void
    Summary: Emit a GFX10+ `RELEASE_MEM` end-of-pipe fence that writes `value` to `gpu_addr` after prior shader work and global-memory writes complete.
    Description: compute-ring fences; older ASICs are not a ZINC_RT direct target.
    Param self: Builder to append to.
    Param gpu_addr: 64-bit GPU virtual address to receive the fence value.
    Param value: Fence payload (typically a monotonically increasing seqno).
    Note: This uses the GFX10+ release-mem packet layout used by amdgpu for
  - PacketBuilder.writeData64 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/#packet-builder-write-data64
    Signature: pub fn writeData64(self: *PacketBuilder, gpu_addr: u64, value: u64) Error!void
    Summary: Emit `WRITE_DATA` that stores `value` (64 bits) at `gpu_addr` via the ME (micro-engine) with WR_CONFIRM set.
    Description: The ME stalls until the write lands in memory (WR_CONFIRM=1), so callers observe the value as soon as the packet retires.
    Param self: Builder to append to.
    Param gpu_addr: Destination GPU virtual address.
    Param value: 64-bit payload written little-endian.
    Note: Uses `dst_sel=5` (memory async/direct) and `engine_sel=0` (ME).
  - PacketBuilder.copyData32 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/#packet-builder-copy-data32
    Signature: pub fn copyData32(self: *PacketBuilder, src_gpu_addr: u64, dst_gpu_addr: u64) Error!void
    Summary: Emit `COPY_DATA` that copies a single 32-bit dword from one GPU memory address to another with WR_CONFIRM set.
    Description: command processor stalls until the destination write completes.
    Param self: Builder to append to.
    Param src_gpu_addr: Source GPU virtual address (memory, src_sel=1).
    Param dst_gpu_addr: Destination GPU virtual address (memory, dst_sel=5).
    Note: Copies exactly 32 bits (count_sel=0). WR_CONFIRM=1 means the
  - PacketBuilder.padToAlignment [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/#packet-builder-pad-to-alignment
    Signature: pub fn padToAlignment(self: *PacketBuilder, dword_alignment: usize) Error!void
    Summary: Pad the buffer with `NOP` packets until the current write cursor is a multiple of `dword_alignment` dwords.
    Description: in a single packet rather than spinning out many minimum-size NOPs.
    Param self: Builder to pad.
    Param dword_alignment: Required alignment in dwords (0 is a no-op).
    Note: Each emitted NOP carries enough payload to land on the alignment

- lo32 [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/#lo32
  Signature: pub fn lo32(value: u64) u32
  Summary: Extract the low 32 bits of a 64-bit value for little-endian dword writes.
  Param value: 64-bit input.
  Returns: Bits [31:0] of `value`.

- hi32 [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/packet/#hi32
  Signature: pub fn hi32(value: u64) u32
  Summary: Extract the high 32 bits of a 64-bit value for little-endian dword writes.
  Param value: 64-bit input.
  Returns: Bits [63:32] of `value`.

### Module: Umq
URL: https://zolotukhin.ai/zinc/docs/zig-api/umq/
Source: src/zinc_rt/ring/umq.zig
Code lines: 306
Summary: AMDGPU user-mode queue (T2) availability and create/free smoke gate.
Overview: AMDGPU uses UMQ for direct submission on Linux kernels that expose the AMDGPU user queue ABI. The preflight is intentionally cheap, while the smoke gate exercises the actual GEM/VA/USERQ_CREATE/USERQ_FREE path required before lowering decode packets onto T2.

- min_linux_major [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/umq/#min-linux-major
  Signature: pub const min_linux_major: u32 = 6
  Summary: Lowest Linux major version that exposes the AMDGPU user-queue ABI used by T2.

- min_linux_minor [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/umq/#min-linux-minor
  Signature: pub const min_linux_minor: u32 = 16
  Summary: Lowest Linux minor version paired with `min_linux_major` for UMQ admission.

- default_render_node [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/umq/#default-render-node
  Signature: pub const default_render_node = "/dev/dri/renderD128"
  Summary: Default render node opened when no caller-supplied path is provided.

- user_queue_param_path [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/umq/#user-queue-param-path
  Signature: pub const user_queue_param_path = "/sys/module/amdgpu/parameters/user_queue"
  Summary: Sysfs path exposing the `amdgpu.user_queue` module parameter that gates UMQ.

- ProbeStatus [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/umq/#probe-status
  Signature: pub const ProbeStatus = enum
  Summary: Outcome of the cheap UMQ preflight check; ordered from success to specific failure modes so callers can report actionable diagnostics.

- KernelVersion [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/umq/#kernel-version
  Signature: pub const KernelVersion = struct
  Summary: Parsed Linux kernel release triple used to compare against `min_linux_*`.

- ProbeResult [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/umq/#probe-result
  Signature: pub const ProbeResult = struct
  Summary: Aggregate output of `probePath` carrying both the verdict and the evidence (kernel version, render node tried, user-queue mode value) used to reach it.
  - ProbeResult.preflightOk [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/umq/#probe-result-preflight-ok
    Signature: pub fn preflightOk(self: ProbeResult) bool
    Summary: Whether the preflight succeeded and the host is eligible for T2 UMQ.
    Param self: Result to inspect.
    Returns: True only when `status == .preflight_ok`.

- SmokeStatus [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/umq/#smoke-status
  Signature: pub const SmokeStatus = enum
  Summary: Outcome of the full create/free smoke gate that exercises the real GEM/VA/USERQ ioctl path required before T2 lowering can run.

- SmokeResult [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/umq/#smoke-result
  Signature: pub const SmokeResult = struct
  Summary: Aggregate output of the UMQ create/free smoke test.
  Description: Carries the verdict, the queue id returned by `USERQ_CREATE` when one was obtained, the upstream errno on ioctl failures, and the firmware-reported metadata (queue slots and EOP buffer requirements) needed to size resources on subsequent runs.
  - SmokeResult.ok [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/umq/#smoke-result-ok
    Signature: pub fn ok(self: SmokeResult) bool
    Summary: True when the smoke gate reached `USERQ_FREE` cleanly.
    Param self: Smoke result to inspect.
    Returns: True only when `status == .passed`.

- probeDefault [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/umq/#probe-default
  Signature: pub fn probeDefault() ProbeResult
  Summary: Run the cheap UMQ preflight against the default render node.
  Returns: A `ProbeResult` describing whether T2 admission is plausible.

- admissionProbeDefault [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/umq/#admission-probe-default
  Signature: pub fn admissionProbeDefault() bool
  Summary: One-shot admission helper combining the preflight and the `kmd.queryComputeUserq` capability query.
  Description: `available` compute user-queue capability.
  Returns: True only when the host both passes preflight and reports an

- createFreeSmokeDefault [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/umq/#create-free-smoke-default
  Signature: pub fn createFreeSmokeDefault() SmokeResult
  Summary: Run the full create/free smoke gate against the default render node.
  Returns: A `SmokeResult` recording every step that succeeded or failed.

- createFreeSmokePath [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/umq/#create-free-smoke-path
  Signature: pub fn createFreeSmokePath(render_node: []const u8) SmokeResult
  Summary: Run the full create/free smoke gate against an explicit render node path.
  Description: Performs preflight, queries the compute user-queue capability, allocates the GEM buffers required by `USERQ_CREATE`, maps their VAs, creates a compute queue, and finally frees it.
  Param render_node: Absolute path to a DRM render node (e.g. `/dev/dri/renderD128`).
  Returns: A `SmokeResult`; inspect `status` and `errno` to localize failures.

- probePath [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/umq/#probe-path
  Signature: pub fn probePath(render_node: []const u8) ProbeResult
  Summary: Cheap preflight that walks the OS, kernel-version, render-node, and `user_queue` module-parameter checks without issuing any ioctls.
  Description: check, or `preflight_ok` when every check passed.
  Param render_node: Path to the DRM render node that would be opened later.
  Returns: A `ProbeResult` whose `status` pinpoints the earliest failing

- kernelSupportsUmq [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/umq/#kernel-supports-umq
  Signature: pub fn kernelSupportsUmq(version: KernelVersion) bool
  Summary: Whether the parsed kernel version meets the minimum required for UMQ.
  Param version: Kernel version produced by `parseKernelRelease`.
  Returns: True when `version >= 6.16`.

- parseKernelRelease [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/umq/#parse-kernel-release
  Signature: pub fn parseKernelRelease(release: []const u8) ?KernelVersion
  Summary: Parse a `uname -r` style release string into a `KernelVersion`.
  Description: Distro suffixes and `-rc` tags after the numeric components are tolerated; the patch component defaults to 0 when absent.
  Param release: Release string such as `6.16.0-24-generic` or `6.16-rc4`.
  Returns: The parsed triple, or null when the leading components are not numeric.

- userQueueModeEnablesUmq [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/umq/#user-queue-mode-enables-umq
  Signature: pub fn userQueueModeEnablesUmq(mode: i32) bool
  Summary: Whether the `amdgpu.user_queue` module-parameter value enables UMQ admission.
  Param mode: Integer read from `/sys/module/amdgpu/parameters/user_queue`.
  Returns: True for `-1` (auto), `1` (enabled), or `2` (forced); false otherwise.

## Sampling

Logit post-processing, argmax helpers, and token-selection controls layered on top of the decode runtime.
URL: https://zolotukhin.ai/zinc/docs/zig-api#sampling

### Module: Argmax
URL: https://zolotukhin.ai/zinc/docs/zig-api/argmax/
Source: src/compute/argmax.zig
Code lines: 123
Summary: Wrap the GPU argmax reduction used for greedy token sampling.
Overview: This helper owns the compute pipeline for the two-phase argmax shader and records the reduction dispatches that pick the next token entirely on GPU.

- ArgmaxDispatch [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/argmax/#argmax-dispatch
  Signature: pub const ArgmaxDispatch = struct
  Summary: GPU-accelerated two-phase argmax reduction for greedy token sampling.
  - ArgmaxDispatch.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/argmax/#argmax-dispatch-init
    Signature: pub fn init( instance: *const Instance, shader_dir: []const u8, allocator: std.mem.Allocator, ) !ArgmaxDispatch
    Summary: Create the argmax compute pipeline and descriptor pool on the given Vulkan instance.
    Param instance: Vulkan instance that owns the device used for all Vulkan calls.
    Param shader_dir: Directory path searched for `argmax.spv`; if the shader is missing the pipeline is set to null and a warning is logged.
    Param allocator: Allocator used internally by the pipeline creation helper.
    Returns: An initialised `ArgmaxDispatch`; the caller must call `deinit` to release GPU resources.
  - ArgmaxDispatch.record [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/argmax/#argmax-dispatch-record
    Signature: pub fn record( self: *const ArgmaxDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, n_logits: u32, phase0_workgroups: u32, ) !void
    Summary: Record the two-phase argmax reduction into a command buffer.
    Description: Phase 0 dispatches `phase0_workgroups` workgroups that each reduce a slice of the logit vector and write partial (value, index) results; phase 1 dispatches a single workgroup that reduces those partials to the final winner. A compute barrier is inserted between the two phases.
    Param cmd: Command buffer to record dispatches into.
    Param descriptor_set: Descriptor set with logits, partials, and result buffers already bound.
    Param n_logits: Total number of logits in the input buffer (vocabulary size).
    Param phase0_workgroups: Number of workgroups launched in phase 0; also the number of partial results consumed by phase 1.
  - ArgmaxDispatch.allocDescriptorSet [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/argmax/#argmax-dispatch-alloc-descriptor-set
    Signature: pub fn allocDescriptorSet(self: *const ArgmaxDispatch) !vk.c.VkDescriptorSet
    Summary: Allocate a descriptor set from the argmax descriptor pool.
    Returns: A freshly allocated `VkDescriptorSet` using the pipeline's layout, or an error if allocation fails or the shader was not loaded.
    Note: The set must be freed back to the pool before calling `deinit`.
  - ArgmaxDispatch.writeDescriptorSet [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/argmax/#argmax-dispatch-write-descriptor-set
    Signature: pub fn writeDescriptorSet( self: *const ArgmaxDispatch, descriptor_set: vk.c.VkDescriptorSet, logits_buf: vk.c.VkBuffer, logits_size: vk.c.VkDeviceSize, partials_buf: vk.c.VkBuffer, partials_size: vk.c.VkDeviceSize, result_buf: vk.c.VkBuffer, result_size: vk.c.VkDeviceSize, ) void
    Summary: Bind the logits, partials, and result buffers to a descriptor set via `vkUpdateDescriptorSets`.
    Description: The three buffers map to shader bindings 0, 1, and 2 respectively.
    Param descriptor_set: Target descriptor set to update (must have been allocated via `allocDescriptorSet`).
    Param logits_buf: Storage buffer containing the raw logit values (shader binding 0).
    Param logits_size: Byte range of `logits_buf` to expose to the shader.
    Param partials_buf: Intermediate storage buffer for phase-0 partial results (shader binding 1).
    Param partials_size: Byte range of `partials_buf` to expose to the shader.
    Param result_buf: Output storage buffer that receives the winning token index after phase 1 (shader binding 2).
    Param result_size: Byte range of `result_buf` to expose to the shader.
  - ArgmaxDispatch.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/argmax/#argmax-dispatch-deinit
    Signature: pub fn deinit(self: *ArgmaxDispatch) void
    Summary: Destroy the pipeline and descriptor pool.

### Module: Argmax
URL: https://zolotukhin.ai/zinc/docs/zig-api/argmax/
Source: src/zinc_rt/isa/cpu_zig/argmax.zig
Code lines: 23
Summary: T-CPU ARGMAX implementation.
Overview: The CPU oracle selects token IDs from logits with deterministic tie behavior that GPU tiers can match during validation.

- Params [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/argmax/#params
  Signature: pub const Params = struct
  Summary: Inputs and outputs for one ARGMAX call.
  Param logits: Flat vector of vocabulary scores; must be non-empty.
  Param output: Destination for the chosen token index (overwritten on success).

- run [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/argmax/#run
  Signature: pub fn run(params: Params) !void
  Summary: Scan the logits vector and write the index of the largest element to `params.output`.
  Description: Ties resolve to the earlier index, matching the GPU oracle.
  Param params: Logits vector and output index slot; the vector must contain at least one value.
  Returns: `error.EmptyInput` when `params.logits.len == 0`, otherwise void.

## Shader Dispatch

Typed wrappers around the compute shaders that prepare push constants, descriptor layouts, and per-op dispatch dimensions.
URL: https://zolotukhin.ai/zinc/docs/zig-api#shader-dispatch

### Module: Attention
URL: https://zolotukhin.ai/zinc/docs/zig-api/attention/
Source: src/compute/attention.zig
Code lines: 220
Summary: Wrap the flash-attention compute shader and its dispatch parameters.
Overview: This helper owns the pipeline resources needed to bind paged attention inputs and record a flash-attention compute pass.

- FlashAttnPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/attention/#flash-attn-push
  Signature: pub const FlashAttnPush = extern struct
  Summary: Push constants for flash attention shader.

- FlashAttnBatchedPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/attention/#flash-attn-batched-push
  Signature: pub const FlashAttnBatchedPush = extern struct
  Summary: Push constants for flash_attn_batched.
  Description: Shared by two callers: - prefill batched path: processes N queries sharing a KV cache, seq_start is the position of the first query (0 on fresh prefill). - decode-shape foundation (ZINC_BATCH_ATTN=1): n_queries=1 with seq_start=state.position, bit-equivalent to the non-batched shader. sink_offset is the per-layer offset into the per-head sinks buffer (layer_idx * n_heads) — honoured by gpt-oss, NaN-gated otherwise.

- FlashAttnSplitMergePush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/attention/#flash-attn-split-merge-push
  Signature: pub const FlashAttnSplitMergePush = extern struct
  Summary: Push constants for flash_attn_split_merge.
  Description: Reads N_I_CHUNKS partial outputs per head from binding 0, applies the per-head sink, normalizes, writes the final output to binding 1.

- AttentionDispatch [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/attention/#attention-dispatch
  Signature: pub const AttentionDispatch = struct
  Summary: Owns the Vulkan compute pipelines for flash attention and records their dispatches into a command buffer.
  Description: Supports three variants: single-query decode (`pipeline`), batched prefill/decode (`pipeline_batched`), and split-K decode (`pipeline_split` + `pipeline_split_merge`). The active variant is selected by the caller; all pipelines are loaded during `init` and destroyed by `deinit`.
  - AttentionDispatch.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/attention/#attention-dispatch-init
    Signature: pub fn init( instance: *const Instance, shader_dir: []const u8, allocator: std.mem.Allocator, ) !AttentionDispatch
    Summary: Create the flash-attention dispatch wrapper and load its shader pipeline.
    Param instance: Active Vulkan instance and logical device.
    Param shader_dir: Directory containing compiled SPIR-V shader binaries.
    Param allocator: Allocator used for temporary pipeline creation state.
    Returns: An AttentionDispatch ready to record flash-attention passes.
  - AttentionDispatch.recordFlashAttn [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/attention/#attention-dispatch-record-flash-attn
    Signature: pub fn recordFlashAttn( self: *const AttentionDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, head_dim: u32, n_heads: u32, n_kv_heads: u32, seq_len: u32, page_size: u32, attn_scale: f32, sink_offset: u32, ) !void
    Summary: Record a flash-attention dispatch for the current decode position.
    Param self: Dispatch wrapper containing the flash-attention pipeline.
    Param cmd: Command buffer currently being recorded.
    Param descriptor_set: Descriptor set containing query, KV-cache, page-table, and output buffers.
    Param head_dim: Hidden width per attention head.
    Param n_heads: Number of query heads to process.
    Param n_kv_heads: Number of KV heads present in the cache.
    Param seq_len: Current decoded sequence length.
    Param page_size: Tokens stored in each KV-cache page.
    Returns: `error.ShaderNotLoaded` when the flash-attention shader pipeline is unavailable.
    Note: The helper dispatches one workgroup per query head.
  - AttentionDispatch.recordFlashAttnBatched [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/attention/#attention-dispatch-record-flash-attn-batched
    Signature: pub fn recordFlashAttnBatched( self: *const AttentionDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, head_dim: u32, n_heads: u32, n_kv_heads: u32, seq_start: u32, n_queries: u32, page_size: u32, attn_scale: f32, sink_offset: u32, ) !void
    Summary: Record a batched flash-attention dispatch.
    Description: Grid is (n_heads, n_queries, 1); each (head, query) workgroup streams over the paged KV cache with causal_len = seq_start + query + 1.
    Param self: Dispatch wrapper containing the batched flash-attention pipeline.
    Param cmd: Command buffer currently being recorded.
    Param descriptor_set: Descriptor set with Q, KV-cache, page-table, output, and sink buffers.
    Param head_dim: Hidden width per attention head.
    Param n_heads: Number of query heads to process.
    Param n_kv_heads: Number of KV heads in the cache (GQA ratio = n_heads / n_kv_heads).
    Param seq_start: Token position of the first query in the sequence (0 on fresh prefill).
    Param n_queries: Number of query tokens processed in this batch.
    Param page_size: Tokens stored per KV-cache page.
    Param attn_scale: Attention softmax scale factor (0 = use 1/sqrt(head_dim)).
    Param sink_offset: Per-layer offset into the sink buffer (layer_idx * n_heads).
    Returns: `error.ShaderNotLoaded` when the batched pipeline is unavailable.
  - AttentionDispatch.recordFlashAttnSplit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/attention/#attention-dispatch-record-flash-attn-split
    Signature: pub fn recordFlashAttnSplit( self: *const AttentionDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, head_dim: u32, n_heads: u32, n_kv_heads: u32, seq_len: u32, page_size: u32, attn_scale: f32, sink_offset: u32, ) !void
    Summary: Record the split-K flash attention dispatch (per-chunk partial pass).
    Description: Grid: (n_heads, fa_split_k_active, 1). Each workgroup runs the standard flash_attn body scoped to its (head, chunk_id) i-range and writes (O_partial, M, L) to the partial output buffer bound at slot 4. Must be followed by `recordFlashAttnSplitMerge` to produce final output.
    Param self: Dispatch wrapper containing the split-K pipeline.
    Param cmd: Command buffer currently being recorded.
    Param descriptor_set: Descriptor set with Q, KV-cache, page-table, partial-output, and sink buffers.
    Param head_dim: Hidden width per attention head.
    Param n_heads: Number of query heads to process.
    Param n_kv_heads: Number of KV heads in the cache (GQA ratio = n_heads / n_kv_heads).
    Param seq_len: Current decoded sequence length (total KV entries to attend over).
    Param page_size: Tokens stored per KV-cache page.
    Param attn_scale: Attention softmax scale factor (0 = use 1/sqrt(head_dim)).
    Param sink_offset: Per-layer offset into the sink buffer (layer_idx * n_heads).
    Returns: `error.ShaderNotLoaded` when the split-K pipeline is unavailable.
  - AttentionDispatch.recordFlashAttnSplitMerge [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/attention/#attention-dispatch-record-flash-attn-split-merge
    Signature: pub fn recordFlashAttnSplitMerge( self: *const AttentionDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, head_dim: u32, n_heads: u32, sink_offset: u32, ) !void
    Summary: Record the split-K merge pass dispatch — combines per-chunk partials for each head, applies the per-head sink term, and writes the final normalized attention output.
    Description: Grid: (n_heads, 1, 1). Must be called after `recordFlashAttnSplit` and a pipeline barrier.
    Param self: Dispatch wrapper containing the split-K merge pipeline.
    Param cmd: Command buffer currently being recorded.
    Param descriptor_set: Descriptor set with partial-input, final-output, and sink buffers (3 bindings).
    Param head_dim: Hidden width per attention head.
    Param n_heads: Number of query heads whose partials are to be merged.
    Param sink_offset: Per-layer offset into the sink buffer (layer_idx * n_heads).
    Returns: `error.ShaderNotLoaded` when the split-K merge pipeline is unavailable.
  - AttentionDispatch.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/attention/#attention-dispatch-deinit
    Signature: pub fn deinit(self: *AttentionDispatch) void
    Summary: Destroy the loaded pipeline and descriptor pool.
    Param self: Dispatch wrapper to tear down in place.

### Module: DMMV
URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/
Source: src/compute/dmmv.zig
Code lines: 5142
Summary: Wrap the decode-time matrix-vector shader family used for projection ops.
Overview: This helper selects quantization-specific DMMV pipelines and records the push constants and workgroup sizes needed for single-token decode.

- DmmvPushConstants [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-push-constants
  Signature: pub const DmmvPushConstants = extern struct
  Summary: Push constants for DMMV shaders (must match GLSL layout).

- BatchDmmvPushConstants [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#batch-dmmv-push-constants
  Signature: pub const BatchDmmvPushConstants = extern struct
  Summary: Push constants for batch DMMV shaders (prefill: multiple columns).

- MoeDmmvPushConstants [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#moe-dmmv-push-constants
  Signature: pub const MoeDmmvPushConstants = extern struct
  Summary: Push constants for MoE DMMV shaders (must match GLSL layout).
  Description: Batched expert dispatch: workgroup Y dimension selects expert slot.

- MoeBatchedDmmvPushConstants [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#moe-batched-dmmv-push-constants
  Signature: pub const MoeBatchedDmmvPushConstants = extern struct
  Summary: Push constants for the cross-token batched MoE DMMV (src/shaders/dmmv_q4k_moe_batched.comp).
  Description: Each WG handles one (row_pair, expert_slot, token_idx) triple; the routing buffer is flattened [n_tokens × n_experts_used] of expert IDs.

- MoeColsDmmvPushConstants [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#moe-cols-dmmv-push-constants
  Signature: pub const MoeColsDmmvPushConstants = extern struct
  Summary: Push constants for grouped route-column MoE DMMV shaders.

- MoeFusedDownAccPushConstants [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#moe-fused-down-acc-push-constants
  Signature: pub const MoeFusedDownAccPushConstants = extern struct
  Summary: Push constants for the fused MoE down + weighted_acc shader (src/shaders/dmmv_q4k_moe_fused_down_acc.comp).
  Description: Same layout as MoeDmmvPushConstants plus n_used (the expert loop is internal to the shader so the dispatch grid drops the Y=n_experts_used dim).

- MoeGateUpGegluPushConstants [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#moe-gate-up-geglu-push-constants
  Signature: pub const MoeGateUpGegluPushConstants = extern struct
  Summary: Push constants for Gemma's packed Q4_K MoE gate+up+GEGLU shader.
  Description: The shader reads expert ids from the routing buffer, so `expert_stride` spans the full packed gate+up expert and `up_offset` selects the up half.

- GemmaTop1MoeBatchPushConstants [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#gemma-top1-moe-batch-push-constants
  Signature: pub const GemmaTop1MoeBatchPushConstants = extern struct
  Summary: Push constants for Gemma short-prefill token-batched top-1 MoE shaders.

- GemmaTop1GateUpColsPushConstants [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#gemma-top1-gate-up-cols-push-constants
  Signature: pub const GemmaTop1GateUpColsPushConstants = extern struct
  Summary: Push constants for route-packed Gemma short-prefill top-1 gate/up+GEGLU.

- OprojMergePushConstants [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#oproj-merge-push-constants
  Signature: pub const OprojMergePushConstants = extern struct
  Summary: Push constants for the fused split-K merge + o_proj DMMV-acc shader (src/shaders/dmmv_q4k_o_proj_merge.comp).
  Description: Adds the merge-pass parameters to the standard DmmvPushConstants so a single dispatch reads partials, computes per-head LSE merge weights, stages attn_out into LDS, and runs the Q4_K matmul with residual accumulation.

- DmmvSigmoidAccPushConstants [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-sigmoid-acc-push-constants
  Signature: pub const DmmvSigmoidAccPushConstants = extern struct
  Summary: Push constants for the fused Q8_0 DMMV + sigmoid-gated scale-accumulate shader (src/shaders/dmmv_q8_0_sigmoid_acc.comp).
  Description: Same prefix as DmmvPushConstants but `acc_mode` is replaced by `gate_offset` (the shader always accumulates and always sigmoid-gates; gate_offset selects which f32 in the gate buffer holds the shexp_gate scalar — typically 0).

- DmmvGateUpGegluPushConstants [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-gate-up-geglu-push-constants
  Signature: pub const DmmvGateUpGegluPushConstants = extern struct
  Summary: Push constants for the Gemma CPU-MoE fused gate+up+GEGLU shader.
  Description: Gate/up offsets are byte offsets into the same packed Q4_K expert tensor; x/y offsets follow the standard DMMV byte convention.

- DmmvScaleAccPushConstants [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-scale-acc-push-constants
  Signature: pub const DmmvScaleAccPushConstants = extern struct
  Summary: Push constants for quantized DMMV fused with `y += scale * dot(W, x)`.

- DmmvQ8PairPushConstants [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-q8-pair-push-constants
  Signature: pub const DmmvQ8PairPushConstants = extern struct
  Summary: Push constants for the fused Q8_0 pair DMMV shader.
  Description: Computes two independent Q8_0 matvecs that share one F32 input vector.

- QuantizeQ8_1Push [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#quantize-q8-1-push
  Signature: pub const QuantizeQ8_1Push = extern struct
  Summary: Push constants for the quantize_q8_1 shader.
  Description: `ne` = number of f32 input elements (must be a multiple of 32). `num_blocks` = ne / 32. Pass explicitly so the shader does not have to divide.

- CountExpertsPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#count-experts-push
  Signature: pub const CountExpertsPush = extern struct
  Summary: Push constants for `count_experts.comp` (effort-6 Step 3 helper). Mirrors the reference implementation's count_experts push so the shader is structurally identical to the upstream version. All strides are in u32 units (not bytes).
  Description: For the prefill routing capture buffer with layout slot(token, layer) = (token * n_layers + layer) * (2 * n_experts_used) where the first n_experts_used u32s are expert IDs and the second n_experts_used u32s are f32 weights, configure as: ne00 = n_experts_used (cells per token row) ne01 = n_tokens (number of token rows) nb00 = 1 (consecutive within slot) nb01 = 2 * n_experts_used * n_layers (skip n_layers slots per row step) a_offset = layer * 2 * n_experts_used (jump to layer's slot in token 0)

- MoeRoutePackPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#moe-route-pack-push
  Signature: pub const MoeRoutePackPush = extern struct
  Summary: Push constants for `moe_route_pack` — turns per-token expert routing into expert-grouped work lists (per-expert counts, packed token IDs, the active-block list, and the indirect dispatch args consumed by the MoE columns kernels).

- MulMmQ4KPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#mul-mm-q4-kpush
  Signature: pub const MulMmQ4KPush = extern struct
  Summary: Push constants for `mul_mm_q4k.comp` (effort-6 Step 1 of 5 foundation: tiled Q4_K dense GEMM).
  Description: Mirrors the dispatch-side argument shape needed to address an M×K Q4_K weight tensor against a K×N f32 activation tile. All offsets follow the existing dmmv convention: `a_offset` is in BYTES (the shader divides by 4 to index a_u32[]), `b_offset` and `d_offset` are in FLOATS. Layout for B/D is column-major: B[col][k] = data_b[b_offset + col*stride_b + k].

- MulMmIdQ4KPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#mul-mm-id-q4-kpush
  Signature: pub const MulMmIdQ4KPush = extern struct
  Summary: Push constants for `mul_mm_id_q4k.comp`, the routed MoE gather sibling of `MulMmQ4KPush`.
  Description: Offsets follow existing GEMM conventions: `a_offset` and `batch_stride_a` are bytes, `b_offset`, `d_offset`, `stride_b`, `stride_d`, and `batch_stride_d` are f32 elements, and `ids_offset` is in u32 elements.

- MulMmQ6KDp4aPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#mul-mm-q6-kdp4a-push
  Signature: pub const MulMmQ6KDp4aPush = extern struct
  Summary: Push constants for the int8 DP4a full-tile Q6_K dense-down GEMM.

- QuantizeActPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#quantize-act-push
  Signature: pub const QuantizeActPush = extern struct
  Summary: Push constants for the one-shot per-32-block activation int8 quantizer.

- MulMmQ4KGateUpDp4aPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#mul-mm-q4-kgate-up-dp4a-push
  Signature: pub const MulMmQ4KGateUpDp4aPush = extern struct
  Summary: Push constants for the int8 DP4a full-tile Q4_K gate+up+SwiGLU GEMM.
  Description: Same fields as `MulMmQ6KDp4aPush` but `stride_b_scale` counts vec2 entries (one per 32-block) so the shader can fetch (scale, dsum) in one read.

- MulMmQ4KGateUpDp4aQ8Push [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#mul-mm-q4-kgate-up-dp4a-q8-push
  Signature: pub const MulMmQ4KGateUpDp4aQ8Push = extern struct
  Summary: Push constants for the int8 DP4a full-tile Q4_K gate+up+SwiGLU GEMM that emits Q8_0-style packed activations directly (fused SwiGLU + quantize for the Qwen3.6-27B dense-down DP4a path).

- Q8_1_BLOCK_BYTES [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#q8-1-block-bytes
  Signature: pub const Q8_1_BLOCK_BYTES: u32 = 36
  Summary: Size in bytes of a single Q8_1 output block (32 int8 values + f16 d + f16 d*sum).

- DmmvDispatch [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch
  Signature: pub const DmmvDispatch = struct
  Summary: Manages DMMV pipelines for different quantization types.
  - DmmvDispatch.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-init
    Signature: pub fn init( instance: *const Instance, gpu_config: *const GpuConfig, shader_dir: []const u8, hidden_dim: u32, allocator: std.mem.Allocator, ) !DmmvDispatch
    Summary: Create the DMMV dispatch wrapper and load the supported quantized pipelines.
    Param instance: Active Vulkan instance and logical device.
    Param gpu_config: Derived GPU tuning parameters (wave size, push-descriptor support).
    Param shader_dir: Directory containing compiled SPIR-V shader binaries (`.spv` files).
    Param hidden_dim: Maximum K value used by the Q4_K and F32 shaders' shared-memory array; must be >= hidden_dim, inter_dim, q_dim, and d_inner.
    Param allocator: Allocator used for temporary pipeline creation state.
    Returns: A fully-initialised DmmvDispatch ready to record projection work; missing shaders are silently set to null.
  - DmmvDispatch.pipelineForType [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-pipeline-for-type
    Signature: pub fn pipelineForType(self: *const DmmvDispatch, quant_type: GGMLType) ?*const Pipeline
    Summary: Select the quantization-specific pipeline used for a weight matrix format.
    Param self: Dispatch wrapper containing the loaded DMMV pipelines.
    Param quant_type: GGML quantization format for the weight matrix.
    Returns: A pipeline pointer when that quantization format has a loaded shader implementation.
    Note: Unsupported or unloaded formats return `null` so callers can surface `error.UnsupportedQuantType`.
  - DmmvDispatch.moePipelineForType [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-moe-pipeline-for-type
    Signature: pub fn moePipelineForType(self: *const DmmvDispatch, quant_type: GGMLType) ?*const Pipeline
    Summary: Select the MoE-specific pipeline for the given weight format (4 bindings: A, x, y, routing).
    Param self: Dispatch wrapper containing the loaded DMMV pipelines.
    Param quant_type: GGML quantization format for the MoE expert weight matrix.
    Returns: A pipeline pointer when a MoE shader is loaded for the format, or null for unsupported types.
  - DmmvDispatch.recordMoeDispatch [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-moe-dispatch
    Signature: pub fn recordMoeDispatch( self: *const DmmvDispatch, cmd: *CommandBuffer, quant_type: GGMLType, descriptor_set: vk.c.VkDescriptorSet, M: u32, K: u32, expert_stride: u32, n_experts_y: u32, x_expert_stride: u32, x_offset: u32, y_offset: u32, ) !void
    Summary: Record a batched MoE DMMV dispatch where all experts run in parallel via Y workgroups.
    Param cmd: Command buffer to record into.
    Param quant_type: Weight quantization; resolved via `moePipelineForType`.
    Param descriptor_set: Descriptor set with bindings A, x, y, routing.
    Param M: Output rows (weight rows per expert).
    Param K: Contraction width (shared across all experts).
    Param expert_stride: Byte stride between consecutive experts in the stacked weight tensor.
    Param n_experts_y: Number of experts to process; becomes the Y workgroup dimension.
    Param x_expert_stride: Element stride between consecutive experts' input vectors (0 = shared input; K = per-expert).
    Param x_offset: Element offset into the input buffer.
    Param y_offset: Element offset into the output buffer.
    Returns: `error.UnsupportedQuantType` when no MoE pipeline is loaded for `quant_type`.
  - DmmvDispatch.recordMoeBatchedDispatch [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-moe-batched-dispatch
    Signature: pub fn recordMoeBatchedDispatch( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, x_buf: vk.c.VkBuffer, x_size: vk.c.VkDeviceSize, y_buf: vk.c.VkBuffer, y_size: vk.c.VkDeviceSize, routing_buf: vk.c.VkBuffer, routing_size: vk.c.VkDeviceSize, M: u32, K: u32, expert_stride: u32, n_experts_used: u32, n_tokens: u32, x_token_stride: u32, y_token_stride: u32, ) !void
    Summary: Record a cross-token batched MoE DMMV dispatch.
    Description: Reads N tokens' inputs from `X_batch[N × K]`, dispatches one WG per (row_pair, expert_slot, token_idx), routes via flattened `routing[N × n_experts_used]`, writes to `Y_batch[N × n_experts_used × M]`. Q4_K only for now.
  - DmmvDispatch.recordMoeRoutePack [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-moe-route-pack
    Signature: pub fn recordMoeRoutePack( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, routing_buf: vk.c.VkBuffer, routing_size: vk.c.VkDeviceSize, counts_buf: vk.c.VkBuffer, counts_size: vk.c.VkDeviceSize, ids_buf: vk.c.VkBuffer, ids_size: vk.c.VkDeviceSize, active_count_buf: vk.c.VkBuffer, active_count_size: vk.c.VkDeviceSize, active_blocks_buf: vk.c.VkBuffer, active_blocks_size: vk.c.VkDeviceSize, dispatch_args_buf: vk.c.VkBuffer, dispatch_args_size: vk.c.VkDeviceSize, n_tokens: u32, n_experts: u32, k: u32, routing_stride: u32, ids_stride: u32, gate_up_workgroups_x: u32, down_workgroups_x: u32, routing_token_base: u32, ) !void
    Summary: Record the single-workgroup `moe_route_pack` dispatch that compacts per-token expert routing into expert-grouped work lists for the MoE columns kernels.
    Description: Reads `routing_buf`/`ids_buf` and writes the per-expert `counts_buf`, the packed `active_blocks_buf` + `active_count_buf`, and `dispatch_args_buf` for the subsequent indirect MoE dispatch. Each buffer is paired with its byte size. `error.InvalidArgument` on a zero token/expert/k/stride/workgroup count.
    Param cmd: Command buffer to record into.
    Param push_desc_fn: Optional push-descriptor function (null uses bound descriptor sets).
    Param n_tokens: Number of tokens being routed.
    Param n_experts: Total expert count in the layer.
    Param k: Experts selected per token (top-k).
    Param routing_stride: Per-token stride (elements) into the routing buffer.
    Param ids_stride: Per-token stride into the packed IDs buffer.
    Param gate_up_workgroups_x: Workgroups-X to encode into the gate/up columns dispatch args.
    Param down_workgroups_x: Workgroups-X to encode into the down columns dispatch args.
    Param routing_token_base: First token offset within the routing buffer.
    Returns: `error.PipelineNotLoaded` if the route-pack pipeline is absent, or
  - DmmvDispatch.recordMoeColsDispatchIndirect [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-moe-cols-dispatch-indirect
    Signature: pub fn recordMoeColsDispatchIndirect( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, quant_type: GGMLType, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, x_buf: vk.c.VkBuffer, x_size: vk.c.VkDeviceSize, y_buf: vk.c.VkBuffer, y_size: vk.c.VkDeviceSize, counts_buf: vk.c.VkBuffer, counts_size: vk.c.VkDeviceSize, ids_buf: vk.c.VkBuffer, ids_size: vk.c.VkDeviceSize, active_blocks_buf: vk.c.VkBuffer, active_blocks_size: vk.c.VkDeviceSize, indirect_buf: vk.c.VkBuffer, indirect_offset: vk.c.VkDeviceSize, M: u32, K: u32, expert_stride: u32, ids_stride: u32, x_route_divisor: u32, a_offset: u32, x_offset: u32, y_offset: u32, accumulate: bool, ) !void
    Summary: Record an **indirect** MoE columns DMMV — the per-expert weight×activation matvec whose workgroup count is read from `indirect_buf` rather than the host.
    Description: Indirect form: the active-block count is GPU-resident (produced by `recordMoeRoutePack`), so the host never stalls on a readback. Each buffer is paired with its byte size. `error.InvalidArgument` on zero M/K/ids_stride or incompatible K alignment.
    Param cmd: Command buffer to record into.
    Param push_desc_fn: Optional push-descriptor function (null uses bound descriptor sets).
    Param quant_type: Weight quantization; supports K-quant columns plus Gemma Q5_1 down rows.
    Param indirect_buf: Buffer holding the `VkDispatchIndirectCommand` workgroup dims.
    Param indirect_offset: Byte offset of the dispatch args within `indirect_buf`.
    Param M: Output rows (expert weight rows).
    Param K: Contraction width; must be a multiple of 256.
    Param expert_stride: Per-expert stride (elements) into the weight buffer.
    Param ids_stride: Per-token stride into the packed IDs buffer.
    Param x_route_divisor: Divisor mapping output rows back to source activation rows.
    Param accumulate: When true, add into `y_buf` instead of overwriting it.
    Returns: `error.UnsupportedQuantType` for unsupported weights, or
  - DmmvDispatch.recordMoeColsQ8_1DispatchIndirect [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-moe-cols-q8-1-dispatch-indirect
    Signature: pub fn recordMoeColsQ8_1DispatchIndirect( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, quant_type: GGMLType, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, x_packed_buf: vk.c.VkBuffer, x_packed_size: vk.c.VkDeviceSize, x_scale_dsum_buf: vk.c.VkBuffer, x_scale_dsum_size: vk.c.VkDeviceSize, y_buf: vk.c.VkBuffer, y_size: vk.c.VkDeviceSize, counts_buf: vk.c.VkBuffer, counts_size: vk.c.VkDeviceSize, ids_buf: vk.c.VkBuffer, ids_size: vk.c.VkDeviceSize, active_blocks_buf: vk.c.VkBuffer, active_blocks_size: vk.c.VkDeviceSize, indirect_buf: vk.c.VkBuffer, indirect_offset: vk.c.VkDeviceSize, M: u32, K: u32, expert_stride: u32, ids_stride: u32, x_route_divisor: u32, a_offset: u32, x_offset: u32, y_offset: u32, accumulate: bool, ) !void
  - DmmvDispatch.recordGemmaTop1GateUpGegluColsDispatchIndirect [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-gemma-top1-gate-up-geglu-cols-dispatch-indirect
    Signature: pub fn recordGemmaTop1GateUpGegluColsDispatchIndirect( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, x_buf: vk.c.VkBuffer, x_size: vk.c.VkDeviceSize, y_buf: vk.c.VkBuffer, y_size: vk.c.VkDeviceSize, counts_buf: vk.c.VkBuffer, counts_size: vk.c.VkDeviceSize, ids_buf: vk.c.VkBuffer, ids_size: vk.c.VkDeviceSize, active_blocks_buf: vk.c.VkBuffer, active_blocks_size: vk.c.VkDeviceSize, indirect_buf: vk.c.VkBuffer, indirect_offset: vk.c.VkDeviceSize, M: u32, K: u32, expert_stride: u32, up_offset: u32, ids_stride: u32, x_route_divisor: u32, a_offset: u32, y_offset: u32, ) !void
  - DmmvDispatch.recordQwenTop1GateUpSwigluColsDispatchIndirect [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-qwen-top1-gate-up-swiglu-cols-dispatch-indirect
    Signature: pub fn recordQwenTop1GateUpSwigluColsDispatchIndirect( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, gate_buf: vk.c.VkBuffer, gate_size: vk.c.VkDeviceSize, up_buf: vk.c.VkBuffer, up_size: vk.c.VkDeviceSize, x_buf: vk.c.VkBuffer, x_size: vk.c.VkDeviceSize, y_buf: vk.c.VkBuffer, y_size: vk.c.VkDeviceSize, counts_buf: vk.c.VkBuffer, counts_size: vk.c.VkDeviceSize, ids_buf: vk.c.VkBuffer, ids_size: vk.c.VkDeviceSize, active_blocks_buf: vk.c.VkBuffer, active_blocks_size: vk.c.VkDeviceSize, indirect_buf: vk.c.VkBuffer, indirect_offset: vk.c.VkDeviceSize, M: u32, K: u32, expert_stride: u32, ids_stride: u32, x_route_divisor: u32, x_token_base: u32, a_offset: u32, y_offset: u32, ) !void
  - DmmvDispatch.recordQwenTop1GateUpSwigluColsQ8_1DispatchIndirect [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-qwen-top1-gate-up-swiglu-cols-q8-1-dispatch-indirect
    Signature: pub fn recordQwenTop1GateUpSwigluColsQ8_1DispatchIndirect( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, gate_buf: vk.c.VkBuffer, gate_size: vk.c.VkDeviceSize, up_buf: vk.c.VkBuffer, up_size: vk.c.VkDeviceSize, x_packed_buf: vk.c.VkBuffer, x_packed_size: vk.c.VkDeviceSize, x_scale_dsum_buf: vk.c.VkBuffer, x_scale_dsum_size: vk.c.VkDeviceSize, y_buf: vk.c.VkBuffer, y_size: vk.c.VkDeviceSize, counts_buf: vk.c.VkBuffer, counts_size: vk.c.VkDeviceSize, ids_buf: vk.c.VkBuffer, ids_size: vk.c.VkDeviceSize, active_blocks_buf: vk.c.VkBuffer, active_blocks_size: vk.c.VkDeviceSize, indirect_buf: vk.c.VkBuffer, indirect_offset: vk.c.VkDeviceSize, M: u32, K: u32, expert_stride: u32, ids_stride: u32, x_route_divisor: u32, x_token_base: u32, a_offset: u32, y_offset: u32, ) !void
  - DmmvDispatch.recordMoeColsDispatch [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-moe-cols-dispatch
    Signature: pub fn recordMoeColsDispatch( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, quant_type: GGMLType, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, x_buf: vk.c.VkBuffer, x_size: vk.c.VkDeviceSize, y_buf: vk.c.VkBuffer, y_size: vk.c.VkDeviceSize, counts_buf: vk.c.VkBuffer, counts_size: vk.c.VkDeviceSize, ids_buf: vk.c.VkBuffer, ids_size: vk.c.VkDeviceSize, active_blocks_buf: vk.c.VkBuffer, active_blocks_size: vk.c.VkDeviceSize, M: u32, K: u32, expert_stride: u32, active_block_count: u32, ids_stride: u32, x_route_divisor: u32, a_offset: u32, x_offset: u32, y_offset: u32, ) !void
    Summary: Record a **direct** MoE columns DMMV using a host-known `active_block_count` (the non-indirect sibling of `recordMoeColsDispatchIndirect`).
    Description: Prefer this when the active block count is already known on the CPU; otherwise use the indirect form to avoid a GPU→CPU readback. This variant always overwrites `y_buf` (no accumulate). Each buffer is paired with its byte size. `error.InvalidArgument` on zero M/K/active_block_count/ids_stride or incompatible K alignment.
    Param cmd: Command buffer to record into.
    Param push_desc_fn: Optional push-descriptor function (null uses bound descriptor sets).
    Param quant_type: Weight quantization; supports route-packed K-quant columns plus Gemma Q5_1 down rows.
    Param M: Output rows (expert weight rows).
    Param K: Contraction width; must match the quantization block alignment.
    Param expert_stride: Per-expert stride (elements) into the weight buffer.
    Param active_block_count: Number of active expert blocks to dispatch (workgroups-Y).
    Param ids_stride: Per-token stride into the packed IDs buffer.
    Param x_route_divisor: Divisor mapping output rows back to source activation rows.
    Returns: `error.UnsupportedQuantType` for unsupported weights, or
  - DmmvDispatch.recordDispatch [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-dispatch
    Signature: pub fn recordDispatch( self: *const DmmvDispatch, cmd: *CommandBuffer, quant_type: GGMLType, descriptor_set: vk.c.VkDescriptorSet, M: u32, K: u32, a_offset: u32, x_offset: u32, y_offset: u32, ) !void
    Summary: Record a decode-time matrix-vector multiply dispatch.
    Param self: Dispatch wrapper containing the quantization-specific pipelines.
    Param cmd: Command buffer currently being recorded.
    Param quant_type: GGML quantization format for the weight matrix.
    Param descriptor_set: Descriptor set containing matrix, input vector, and output buffers.
    Param M: Output row count.
    Param K: Input feature width.
    Param a_offset: Byte offset for the weight matrix.
    Param x_offset: Byte offset for the input vector.
    Param y_offset: Byte offset for the output vector.
    Returns: `error.UnsupportedQuantType` when no pipeline is available for `quant_type`.
    Note: The helper uses one workgroup per 2 output rows for most quantized formats.
  - DmmvDispatch.recordBatchDispatchPush [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-batch-dispatch-push
    Signature: pub fn recordBatchDispatchPush( self: *const DmmvDispatch, cmd: *CommandBuffer, quant_type: GGMLType, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, x_buf: vk.c.VkBuffer, x_size: vk.c.VkDeviceSize, y_buf: vk.c.VkBuffer, y_size: vk.c.VkDeviceSize, M: u32, K: u32, a_offset: u32, x_offset: u32, y_offset: u32, num_cols: u32, ) !void
    Summary: Record a push-descriptor batch DMMV dispatch covering `num_cols` token columns.
    Description: Bindings: 0 = A weight matrix, 1 = X_batch (K × num_cols, column-major), 2 = Y_batch (M × num_cols, column-major).
    Param cmd: Command buffer to record into.
    Param quant_type: Weight quantization; only Q4_K and Q6_K batch shaders are supported.
    Param push_desc_fn: Push-descriptor function pointer (null falls back to bound descriptor sets).
    Param M: Output row count (weight matrix rows).
    Param K: Contraction width (hidden dimension).
    Param num_cols: Number of token columns to process in this batch.
    Returns: `error.UnsupportedQuantType` if no batch shader is loaded for `quant_type`.
  - DmmvDispatch.recordQuantizeQ8_1 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-quantize-q8-1
    Signature: pub fn recordQuantizeQ8_1( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, ne: u32, ) !void
    Summary: Record a dispatch that quantizes `ne` f32 elements from `a_buf` into Q8_1 blocks (36 bytes each) in `d_buf`.
    Description: Foundation for mul_mmq — no production callers yet. Requires `ne` to be a multiple of 32. Returns `error.PipelineNotLoaded` when the shader is unavailable, `error.InvalidArgument` when ne is not a multiple of 32.
  - DmmvDispatch.recordCountExperts [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-count-experts
    Signature: pub fn recordCountExperts( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, routing_buf: vk.c.VkBuffer, routing_size: vk.c.VkDeviceSize, counts_buf: vk.c.VkBuffer, counts_size: vk.c.VkDeviceSize, n_tokens: u32, n_layers: u32, layer: u32, n_experts_used: u32, n_experts: u32, d_offset_bytes: vk.c.VkDeviceSize, ) !void
    Summary: Effort 6 Step 3: dispatch the count_experts shader. For one layer, scan a routing buffer that stores per-(token, layer) topk expert IDs and produce a `[n_experts]` u32 count buffer.
    Description: Layout assumed for `routing_buf`: slot(token, layer) starts at byte offset (token * n_layers + layer) * (2 * n_experts_used) * 4 the first n_experts_used u32s are expert IDs, the next n_experts_used u32s are f32 weights (mirrors router_output_buf packing in forward.zig:5316+).
    Description: `counts_buf` must be sized for at least `n_experts * sizeof(u32)`. Caller is responsible for clearing or overwriting it (the shader writes one element per expert, indexed by gl_WorkGroupID.x).
    Description: Returns `error.PipelineNotLoaded` if the count_experts shader is unavailable, `error.InvalidArgument` for zero token counts.
  - DmmvDispatch.recordMulMmQ4K [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q4-k
    Signature: pub fn recordMulMmQ4K( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, b_buf: vk.c.VkBuffer, b_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, stride_b: u32, stride_d: u32, a_offset: u32, b_offset: u32, d_offset: u32, ) !void
    Summary: Effort-6 Step 1: dispatch the tiled Q4_K dense GEMM (`mul_mm_q4k.comp`). Computes D[M, N] = A[M, K] (Q4_K) × B[K, N] (f32), where B and D are column-major (B[col][k] = data_b[b_offset + col*stride_b + k], analogously for D).
    Description: Tile shape: WG = 64 threads producing a 32 × 32 output tile. Dispatch grid: ((M+31)/32) × ((N+31)/32) × 1.
    Description: Constraints: - K must be a multiple of 256 (Q4_K super-block size). - `a_offset` is in BYTES; `b_offset` and `d_offset` are in FLOATS. - Caller is responsible for any preceding clear of D.
    Description: Returns `error.PipelineNotLoaded` if mul_mm_q4k.spv isn't loaded, `error.InvalidArgument` for K-misaligned inputs.
  - DmmvDispatch.recordMulMmIdQ4K [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-id-q4-k
    Signature: pub fn recordMulMmIdQ4K( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, b_buf: vk.c.VkBuffer, b_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, ids_buf: vk.c.VkBuffer, ids_size: vk.c.VkDeviceSize, counts_buf: vk.c.VkBuffer, counts_size: vk.c.VkDeviceSize, M: u32, K: u32, stride_b: u32, stride_d: u32, batch_stride_a: u32, batch_stride_d: u32, nei0: u32, nei1: u32, nbi1: u32, a_offset: u32, b_offset: u32, d_offset: u32, ids_offset: u32, n_experts: u32, n_tile_y: u32, ) !void
    Summary: Dispatch the routed tiled Q4_K MoE GEMM (`mul_mm_id_q4k.comp`).
    Description: One dispatch covers all experts: grid.x tiles output rows, grid.y tiles routed token/slot columns per expert, and grid.z is expert id. `counts_buf[e]` must contain the number of token/slot pairs routed to expert `e`; `ids_buf` is the token-major top-k route table scanned by the shader. This path is a validation foundation and is not selected by production prefill yet.
  - DmmvDispatch.recordMulMmQ4KDownAcc [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q4-kdown-acc
    Signature: pub fn recordMulMmQ4KDownAcc( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, b_buf: vk.c.VkBuffer, b_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, stride_b: u32, stride_d: u32, a_offset: u32, b_offset: u32, d_offset: u32, ) !void
    Summary: Tiled Q4_K dense GEMM with fused-residual accumulate: identical to recordMulMmQ4K but the output ACCUMULATES into D (d[idx] += result) instead of overwriting.
    Description: Eliminates the standalone barrier + scale_accumulate dispatch for the dense-FFN residual add. Ragged shapes (M or N not multiples of 32) are handled by boundary checks in the shader.
    Param M: Output rows (weight rows, i.e. hidden_dim for down projection).
    Param N: Token batch size (number of columns).
    Param K: Contraction width; must be a multiple of 256.
    Returns: `error.PipelineNotLoaded` if the acc pipeline is absent, or `error.InvalidArgument` for zero/misaligned K or zero M/N.
  - DmmvDispatch.recordMulMmQ4KDownAccWide [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q4-kdown-acc-wide
    Signature: pub fn recordMulMmQ4KDownAccWide( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, b_buf: vk.c.VkBuffer, b_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, stride_b: u32, stride_d: u32, a_offset: u32, b_offset: u32, d_offset: u32, ) !void
    Summary: Wide-tile (BN=64) variant of recordMulMmQ4KDownAcc.
    Description: Each WG produces a 32×64 output tile. Caller must ensure N is a multiple of 64 for full efficiency (the shader handles ragged N via bounds checks).
  - DmmvDispatch.recordMulMmQ4KGateUpSwiglu [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q4-kgate-up-swiglu
    Signature: pub fn recordMulMmQ4KGateUpSwiglu( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, gate_buf: vk.c.VkBuffer, gate_size: vk.c.VkDeviceSize, up_buf: vk.c.VkBuffer, up_size: vk.c.VkDeviceSize, b_buf: vk.c.VkBuffer, b_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, stride_b: u32, stride_d: u32, a_offset: u32, b_offset: u32, d_offset: u32, ) !void
    Summary: Tiled Q4_K batched dense FFN front-end: computes silu(gate_weight * B) * (up_weight * B) directly into D.
    Description: Ragged (M or N not multiples of 32) shapes are handled by boundary checks in the shader.
    Param M: Output rows (gate/up weight rows, i.e. inter_dim).
    Param N: Token batch size (number of columns).
    Param K: Contraction width; must be a multiple of 256.
    Returns: `error.PipelineNotLoaded` if the gate+up+SwiGLU pipeline is absent, or `error.InvalidArgument` for zero/misaligned K or zero M/N.
  - DmmvDispatch.recordMulMmQ4KTail8 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q4-ktail8
    Signature: pub fn recordMulMmQ4KTail8( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, b_buf: vk.c.VkBuffer, b_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, stride_b: u32, stride_d: u32, a_offset: u32, b_offset: u32, d_offset: u32, ) !void
    Summary: BN=8 Q4_K GEMM for narrow token tails after the generic 32-column path.
    Description: Requires row-aligned M; N may be 1..8 and is bounds-checked in-shader.
  - DmmvDispatch.recordMulMmQ4KGateUpGeglu [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q4-kgate-up-geglu
    Signature: pub fn recordMulMmQ4KGateUpGeglu( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, gate_buf: vk.c.VkBuffer, gate_size: vk.c.VkDeviceSize, up_buf: vk.c.VkBuffer, up_size: vk.c.VkDeviceSize, b_buf: vk.c.VkBuffer, b_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, stride_b: u32, stride_d: u32, a_offset: u32, b_offset: u32, d_offset: u32, ) !void
    Summary: Tiled Q4_K batched Gemma dense FFN front-end: computes gelu(gate_weight * B) * (up_weight * B) directly into D.
    Description: Same binding and push layout as recordMulMmQ4KGateUpSwiglu.
  - DmmvDispatch.recordMulMmQ4KGateUpGegluFull [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q4-kgate-up-geglu-full
    Signature: pub fn recordMulMmQ4KGateUpGegluFull( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, gate_buf: vk.c.VkBuffer, gate_size: vk.c.VkDeviceSize, up_buf: vk.c.VkBuffer, up_size: vk.c.VkDeviceSize, b_buf: vk.c.VkBuffer, b_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, stride_b: u32, stride_d: u32, a_offset: u32, b_offset: u32, d_offset: u32, ) !void
    Summary: Branchless full-tile Q4_K gate/up/GEGLU GEMM for Gemma dense prefill.
    Description: Requires M and N to be multiples of 32; ragged token tails use the checked recordMulMmQ4KGateUpGeglu path.
  - DmmvDispatch.recordMulMmQ4KGateUpGegluTail8 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q4-kgate-up-geglu-tail8
    Signature: pub fn recordMulMmQ4KGateUpGegluTail8( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, gate_buf: vk.c.VkBuffer, gate_size: vk.c.VkDeviceSize, up_buf: vk.c.VkBuffer, up_size: vk.c.VkDeviceSize, b_buf: vk.c.VkBuffer, b_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, stride_b: u32, stride_d: u32, a_offset: u32, b_offset: u32, d_offset: u32, ) !void
    Summary: BN=8 Q4_K gate/up/GEGLU GEMM for narrow token tails after the 32-column full-tile path.
    Description: Requires row-aligned M; N may be 1..8.
  - DmmvDispatch.recordMulMmQ4KGateUpSwigluFull [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q4-kgate-up-swiglu-full
    Signature: pub fn recordMulMmQ4KGateUpSwigluFull( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, gate_buf: vk.c.VkBuffer, gate_size: vk.c.VkDeviceSize, up_buf: vk.c.VkBuffer, up_size: vk.c.VkDeviceSize, b_buf: vk.c.VkBuffer, b_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, stride_b: u32, stride_d: u32, a_offset: u32, b_offset: u32, d_offset: u32, ) !void
    Summary: Branchless full-tile Q4_K gate/up/SwiGLU GEMM.
    Description: Requires M and N to be multiples of 32; ragged token tails use the checked recordMulMmQ4KGateUpSwiglu path.
  - DmmvDispatch.recordMulMmQ6K [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q6-k
    Signature: pub fn recordMulMmQ6K( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, b_buf: vk.c.VkBuffer, b_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, stride_b: u32, stride_d: u32, a_offset: u32, b_offset: u32, d_offset: u32, ) !void
    Summary: Tiled Q6_K dense GEMM.
    Description: Same push/layout as recordMulMmQ4K. Used by Qwen3.6-27B layer-major prefill for dense-down and SSM wqkv.
  - DmmvDispatch.recordMulMmQ6KTail8 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q6-ktail8
    Signature: pub fn recordMulMmQ6KTail8( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, b_buf: vk.c.VkBuffer, b_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, stride_b: u32, stride_d: u32, a_offset: u32, b_offset: u32, d_offset: u32, ) !void
    Summary: BN=8 Q6_K GEMM for narrow token tails after the 32-column full-tile path.
    Description: Requires row-aligned M; N may be 1..8 and is bounds-checked in-shader.
  - DmmvDispatch.recordMulMmQ5K [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q5-k
    Signature: pub fn recordMulMmQ5K( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, b_buf: vk.c.VkBuffer, b_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, stride_b: u32, stride_d: u32, a_offset: u32, b_offset: u32, d_offset: u32, ) !void
    Summary: Tiled Q5_K dense GEMM.
    Description: Same push/layout as recordMulMmQ4K/recordMulMmQ6K. Used by Qwen3.6-27B layer-major prefill for the SSM out projection, which otherwise falls through to the dmmv_q5k one-WG-per-row batched path.
  - DmmvDispatch.recordMulMmQ5KWide [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q5-kwide
    Signature: pub fn recordMulMmQ5KWide( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, b_buf: vk.c.VkBuffer, b_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, stride_b: u32, stride_d: u32, a_offset: u32, b_offset: u32, d_offset: u32, ) !void
    Summary: Wide-tile (BN=64) variant of recordMulMmQ5K.
    Description: Each WG produces a 32×64 output tile. Halves weight VRAM traffic for N=64 prefill.
  - DmmvDispatch.recordMulMmQ8_0 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q8-0
    Signature: pub fn recordMulMmQ8_0( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, b_buf: vk.c.VkBuffer, b_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, stride_b: u32, stride_d: u32, a_offset: u32, b_offset: u32, d_offset: u32, ) !void
    Summary: Tiled Q8_0 dense GEMM for Qwen3.6 A3B layer-major prefill (SSM out projection).
    Description: Uses the same `MulMmQ4KPush` layout as `recordMulMmQ4K`, but K must be a multiple of 32 (not 256).
    Returns: `error.PipelineNotLoaded` if the Q8_0 GEMM pipeline is absent, or `error.InvalidArgument` for K not a multiple of 32 or zero M/N.
  - DmmvDispatch.recordMulMmQ8_0FullDp4a [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q8-0-full-dp4a
    Signature: pub fn recordMulMmQ8_0FullDp4a( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, b_packed_buf: vk.c.VkBuffer, b_packed_size: vk.c.VkDeviceSize, b_scale_buf: vk.c.VkBuffer, b_scale_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, a_offset: u32, d_offset: u32, ) !void
    Summary: Record an int8 DP4a full-tile Q8_0 GEMM.
    Description: The activation must already be quantized with recordQuantizeActQ8. Ragged token tails stay on the f32 recordMulMmQ8_0 path at the call site.
  - DmmvDispatch.recordMulMmQ6KFull [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q6-kfull
    Signature: pub fn recordMulMmQ6KFull( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, b_buf: vk.c.VkBuffer, b_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, stride_b: u32, stride_d: u32, a_offset: u32, b_offset: u32, d_offset: u32, ) !void
    Summary: Branchless full-tile Q6_K GEMM for 32-aligned token counts; the host routes only 32-aligned M/N tiles here.
    Returns: `error.PipelineNotLoaded` if the full-tile pipeline is absent, or `error.InvalidArgument` for misaligned or zero dimensions.
    Note: M and N must both be multiples of 32; ragged tails must use `recordMulMmQ6K` instead.
  - DmmvDispatch.recordMulMmQ6KFullDownAcc [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q6-kfull-down-acc
    Signature: pub fn recordMulMmQ6KFullDownAcc( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, b_buf: vk.c.VkBuffer, b_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, stride_b: u32, stride_d: u32, a_offset: u32, b_offset: u32, d_offset: u32, ) !void
    Summary: Fused-residual variant of `recordMulMmQ6KFull`: the output ACCUMULATES into d_data (d[idx] += result) instead of overwriting.
    Description: This eliminates the standalone barrier + scale_accumulate dispatch that adds the dense-FFN residual. Same shape constraints as `recordMulMmQ6KFull`.
  - DmmvDispatch.recordQuantizeActQ8 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-quantize-act-q8
    Signature: pub fn recordQuantizeActQ8( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, src_buf: vk.c.VkBuffer, src_size: vk.c.VkDeviceSize, dst_packed_buf: vk.c.VkBuffer, dst_packed_size: vk.c.VkDeviceSize, dst_scale_buf: vk.c.VkBuffer, dst_scale_size: vk.c.VkDeviceSize, n_tokens: u32, K: u32, ) !void
    Summary: Quantize an f32 activation matrix to packed int8 + per-32-block scales (one shot, no per-tile redundancy) for the int8 DP4a dense-down GEMM.
    Param src_buf: token-major f32 activation [n_tokens][K].
    Param dst_packed_buf: token-major packed int8 [n_tokens][K/4] (4 lanes/uint).
    Param dst_scale_buf: token-major f32 scale [n_tokens][K/32].
  - DmmvDispatch.recordMulMmQ6KFullDp4a [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q6-kfull-dp4a
    Signature: pub fn recordMulMmQ6KFullDp4a( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, b_packed_buf: vk.c.VkBuffer, b_packed_size: vk.c.VkDeviceSize, b_scale_buf: vk.c.VkBuffer, b_scale_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, a_offset: u32, d_offset: u32, accumulate: bool, ) !void
    Summary: Record the int8 DP4a full-tile Q6_K dense-down GEMM.
    Description: Weights are Q6_K; the activation arrives pre-quantized (packed int8 + per-32-block f32 scale) from recordQuantizeActQ8. Output is token-major f32 [N][M].
  - DmmvDispatch.recordMulMmQ6KFullDp4aN64InterleavedAcc [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q6-kfull-dp4a-n64-interleaved-acc
    Signature: pub fn recordMulMmQ6KFullDp4aN64InterleavedAcc( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, b_packed_buf: vk.c.VkBuffer, b_packed_size: vk.c.VkDeviceSize, b_scale_buf: vk.c.VkBuffer, b_scale_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, a_offset: u32, d_offset: u32, ) !void
  - DmmvDispatch.recordMulMmQ6KRagged72Dp4a [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q6-kragged72-dp4a
    Signature: pub fn recordMulMmQ6KRagged72Dp4a( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, b_packed_buf: vk.c.VkBuffer, b_packed_size: vk.c.VkDeviceSize, b_scale_buf: vk.c.VkBuffer, b_scale_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, a_offset: u32, d_offset: u32, ) !void
    Summary: Guarded BN=72 int8 DP4a Q6_K dense-down GEMM for Gemma 4 31B's 65-72 token public prompt shape.
    Description: This covers the 64-column body and <=8-column ragged tail in one pass over the K=21504 down weights.
  - DmmvDispatch.recordMulMmQ6KTail8Dp4a [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q6-ktail8-dp4a
    Signature: pub fn recordMulMmQ6KTail8Dp4a( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, b_packed_buf: vk.c.VkBuffer, b_packed_size: vk.c.VkDeviceSize, b_scale_buf: vk.c.VkBuffer, b_scale_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, a_offset: u32, b_packed_offset: u32, b_scale_offset: u32, d_offset: u32, ) !void
    Summary: BN=8 int8 DP4a Q6_K dense-down tail for Gemma 4 31B short prompts.
    Description: The packed/scaled activation descriptors are offset to the first tail token, while the output uses d_offset so the token-major destination layout remains contiguous with the full 64-token prefix.
  - DmmvDispatch.recordMulMmQ6KFullDp4aQ8_1 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q6-kfull-dp4a-q8-1
    Signature: pub fn recordMulMmQ6KFullDp4aQ8_1( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, b_packed_buf: vk.c.VkBuffer, b_packed_size: vk.c.VkDeviceSize, b_scale_dsum_buf: vk.c.VkBuffer, b_scale_dsum_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, a_offset: u32, d_offset: u32, ) !void
    Summary: Q8_1-input variant: same Q6_K DP4a GEMM but the activation scale buffer is `vec2 b_scale_dsum[]` per 32-block (Q4_K-style layout).
    Description: The shader reads `.x` only — `.y` (dsum) is unused since Q6_K weights have no per-block bias term. Used by the Qwen3.6-27B SSM wqkv projection so it can share a single Q8_1 quantize of scratch_norm with the Q4_K z projection. Push constant stride_b_scale = K/32 (number of vec2 entries per token), same numeric value as the Q8_0 variant since the indexing is in typed-element units.
  - DmmvDispatch.recordQuantizeActQ8_1 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-quantize-act-q8-1
    Signature: pub fn recordQuantizeActQ8_1( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, src_buf: vk.c.VkBuffer, src_size: vk.c.VkDeviceSize, dst_packed_buf: vk.c.VkBuffer, dst_packed_size: vk.c.VkDeviceSize, dst_scale_dsum_buf: vk.c.VkBuffer, dst_scale_dsum_size: vk.c.VkDeviceSize, n_tokens: u32, K: u32, ) !void
    Summary: Q8_1-style activation quantize: packed int8 + per-32-block (scale, dsum) for the DP4a Q4_K gate+up GEMM bias-correction term.
  - DmmvDispatch.recordMulMmQ4KGateUpSwigluFullDp4a [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q4-kgate-up-swiglu-full-dp4a
    Signature: pub fn recordMulMmQ4KGateUpSwigluFullDp4a( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, gate_buf: vk.c.VkBuffer, gate_size: vk.c.VkDeviceSize, up_buf: vk.c.VkBuffer, up_size: vk.c.VkDeviceSize, b_packed_buf: vk.c.VkBuffer, b_packed_size: vk.c.VkDeviceSize, b_scale_dsum_buf: vk.c.VkBuffer, b_scale_dsum_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, a_offset: u32, d_offset: u32, ) !void
    Summary: int8 DP4a full-tile Q4_K gate+up+SwiGLU GEMM for Qwen3.6-27B dense FFN prefill.
    Description: Activations arrive pre-quantized from recordQuantizeActQ8_1 (packed int8 + per-32-block (scale, dsum)). Output is silu(gate)*up, token-major f32 [N][M].
  - DmmvDispatch.recordMulMmQ4KGateUpGegluFullDp4a [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q4-kgate-up-geglu-full-dp4a
    Signature: pub fn recordMulMmQ4KGateUpGegluFullDp4a( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, gate_buf: vk.c.VkBuffer, gate_size: vk.c.VkDeviceSize, up_buf: vk.c.VkBuffer, up_size: vk.c.VkDeviceSize, b_packed_buf: vk.c.VkBuffer, b_packed_size: vk.c.VkDeviceSize, b_scale_dsum_buf: vk.c.VkBuffer, b_scale_dsum_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, a_offset: u32, d_offset: u32, ) !void
    Summary: int8 DP4a full-tile Q4_K gate+up+GEGLU GEMM for Gemma dense FFN prefill.
    Description: Activations arrive pre-quantized from recordQuantizeActQ8_1 (packed int8 + per-32-block (scale, dsum)). Output is gelu(gate)*up, token-major f32 [N][M].
  - DmmvDispatch.recordMulMmQ4KGateUpSwigluFullDp4aQ8 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q4-kgate-up-swiglu-full-dp4a-q8
    Signature: pub fn recordMulMmQ4KGateUpSwigluFullDp4aQ8( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, gate_buf: vk.c.VkBuffer, gate_size: vk.c.VkDeviceSize, up_buf: vk.c.VkBuffer, up_size: vk.c.VkDeviceSize, b_packed_buf: vk.c.VkBuffer, b_packed_size: vk.c.VkDeviceSize, b_scale_dsum_buf: vk.c.VkBuffer, b_scale_dsum_size: vk.c.VkDeviceSize, d_packed_buf: vk.c.VkBuffer, d_packed_size: vk.c.VkDeviceSize, d_scale_buf: vk.c.VkBuffer, d_scale_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, a_offset: u32, d_packed_offset: u32, d_scale_offset: u32, ) !void
    Summary: int8 DP4a full-tile Q4_K gate+up+SwiGLU GEMM that emits Q8_0-style packed activation directly.
    Description: Output layout matches quantize_act_q8.comp (per-token packed int8 + per-32-block scale), so the downstream dense-down DP4a kernel can consume it directly without the standalone quantize_act_q8 dispatch + barrier. The f32 SwiGLU intermediate is never written to global memory.
  - DmmvDispatch.recordMulMmQ4KGateUpSwigluFullDp4aQ8N64Interleaved [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q4-kgate-up-swiglu-full-dp4a-q8-n64-interleaved
    Signature: pub fn recordMulMmQ4KGateUpSwigluFullDp4aQ8N64Interleaved( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, gate_buf: vk.c.VkBuffer, gate_size: vk.c.VkDeviceSize, up_buf: vk.c.VkBuffer, up_size: vk.c.VkDeviceSize, b_packed_buf: vk.c.VkBuffer, b_packed_size: vk.c.VkDeviceSize, b_scale_dsum_buf: vk.c.VkBuffer, b_scale_dsum_size: vk.c.VkDeviceSize, d_packed_buf: vk.c.VkBuffer, d_packed_size: vk.c.VkDeviceSize, d_scale_buf: vk.c.VkBuffer, d_scale_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, a_offset: u32, d_packed_offset: u32, d_scale_offset: u32, ) !void
  - DmmvDispatch.recordMulMmQ4KGateUpGegluFullDp4aQ8 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q4-kgate-up-geglu-full-dp4a-q8
    Signature: pub fn recordMulMmQ4KGateUpGegluFullDp4aQ8( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, gate_buf: vk.c.VkBuffer, gate_size: vk.c.VkDeviceSize, up_buf: vk.c.VkBuffer, up_size: vk.c.VkDeviceSize, b_packed_buf: vk.c.VkBuffer, b_packed_size: vk.c.VkDeviceSize, b_scale_dsum_buf: vk.c.VkBuffer, b_scale_dsum_size: vk.c.VkDeviceSize, d_packed_buf: vk.c.VkBuffer, d_packed_size: vk.c.VkDeviceSize, d_scale_buf: vk.c.VkBuffer, d_scale_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, a_offset: u32, b_packed_offset: u32, b_scale_offset: u32, d_packed_offset: u32, d_scale_offset: u32, ) !void
    Summary: Gemma GEGLU variant of recordMulMmQ4KGateUpSwigluFullDp4aQ8.
    Description: Emits Q8_0-style packed GEGLU activation for Q6_K dense-down DP4a.
  - DmmvDispatch.recordMulMmQ4KGateUpGegluN1Dp4aQ8 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q4-kgate-up-geglu-n1-dp4a-q8
    Signature: pub fn recordMulMmQ4KGateUpGegluN1Dp4aQ8( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, gate_buf: vk.c.VkBuffer, gate_size: vk.c.VkDeviceSize, up_buf: vk.c.VkBuffer, up_size: vk.c.VkDeviceSize, b_packed_buf: vk.c.VkBuffer, b_packed_size: vk.c.VkDeviceSize, b_scale_dsum_buf: vk.c.VkBuffer, b_scale_dsum_size: vk.c.VkDeviceSize, d_packed_buf: vk.c.VkBuffer, d_packed_size: vk.c.VkDeviceSize, d_scale_buf: vk.c.VkBuffer, d_scale_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, a_offset: u32, b_packed_offset: u32, b_scale_offset: u32, d_packed_offset: u32, d_scale_offset: u32, ) !void
    Summary: Single-token Gemma GEGLU producer for Q6_K-down decode.
    Description: Same bindings and push layout as recordMulMmQ4KGateUpGegluFullDp4aQ8, but fixed to one token so all lanes do useful work instead of guarding seven BN=8 columns.
  - DmmvDispatch.recordMulMmQ4KGateUpSwigluFullDp4aQ8_1 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q4-kgate-up-swiglu-full-dp4a-q8-1
    Signature: pub fn recordMulMmQ4KGateUpSwigluFullDp4aQ8_1( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, gate_buf: vk.c.VkBuffer, gate_size: vk.c.VkDeviceSize, up_buf: vk.c.VkBuffer, up_size: vk.c.VkDeviceSize, b_packed_buf: vk.c.VkBuffer, b_packed_size: vk.c.VkDeviceSize, b_scale_dsum_buf: vk.c.VkBuffer, b_scale_dsum_size: vk.c.VkDeviceSize, d_packed_buf: vk.c.VkBuffer, d_packed_size: vk.c.VkDeviceSize, d_scale_dsum_buf: vk.c.VkBuffer, d_scale_dsum_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, a_offset: u32, d_packed_offset: u32, d_scale_dsum_offset: u32, ) !void
    Summary: Q4_K-down sibling of recordMulMmQ4KGateUpSwigluFullDp4aQ8.
    Description: Same fused gate+up+SwiGLU DP4a GEMM, but emits Q8_1-style activation (packed int8 + per-32-block (scale, dsum) vec2) so the downstream mul_mm_q4k_full_dp4a (Q4_K-down) consumer can skip the standalone quantize_act_q8_1 dispatch + barrier. dsum = scale * sum(int8_lanes) is computed inside the kernel via subgroupClusteredAdd cluster_size=TPR_M=8, so there's no LDS round-trip beyond the GEMM's existing barriers. Caller is responsible for sizing d_scale_dsum_buf as 2x the Q8_0 scale buffer (per-block vec2 instead of per-block float).
  - DmmvDispatch.recordMulMmQ4KGateUpSwigluFullDp4aQ8_1N64Interleaved [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q4-kgate-up-swiglu-full-dp4a-q8-1-n64-interleaved
    Signature: pub fn recordMulMmQ4KGateUpSwigluFullDp4aQ8_1N64Interleaved( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, gate_buf: vk.c.VkBuffer, gate_size: vk.c.VkDeviceSize, up_buf: vk.c.VkBuffer, up_size: vk.c.VkDeviceSize, b_packed_buf: vk.c.VkBuffer, b_packed_size: vk.c.VkDeviceSize, b_scale_dsum_buf: vk.c.VkBuffer, b_scale_dsum_size: vk.c.VkDeviceSize, d_packed_buf: vk.c.VkBuffer, d_packed_size: vk.c.VkDeviceSize, d_scale_dsum_buf: vk.c.VkBuffer, d_scale_dsum_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, a_offset: u32, d_packed_offset: u32, d_scale_dsum_offset: u32, ) !void
  - DmmvDispatch.recordMulMmQ4KGateUpGegluFullDp4aQ8_1 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q4-kgate-up-geglu-full-dp4a-q8-1
    Signature: pub fn recordMulMmQ4KGateUpGegluFullDp4aQ8_1( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, gate_buf: vk.c.VkBuffer, gate_size: vk.c.VkDeviceSize, up_buf: vk.c.VkBuffer, up_size: vk.c.VkDeviceSize, b_packed_buf: vk.c.VkBuffer, b_packed_size: vk.c.VkDeviceSize, b_scale_dsum_buf: vk.c.VkBuffer, b_scale_dsum_size: vk.c.VkDeviceSize, d_packed_buf: vk.c.VkBuffer, d_packed_size: vk.c.VkDeviceSize, d_scale_dsum_buf: vk.c.VkBuffer, d_scale_dsum_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, a_offset: u32, b_packed_offset: u32, b_scale_offset: u32, d_packed_offset: u32, d_scale_dsum_offset: u32, ) !void
    Summary: Gemma GEGLU variant of recordMulMmQ4KGateUpSwigluFullDp4aQ8_1.
    Description: Emits Q8_1-style packed GEGLU activation for Q4_K dense-down DP4a.
  - DmmvDispatch.recordMulMmQ5KFullDp4a [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q5-kfull-dp4a
    Signature: pub fn recordMulMmQ5KFullDp4a( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, b_packed_buf: vk.c.VkBuffer, b_packed_size: vk.c.VkDeviceSize, b_scale_dsum_buf: vk.c.VkBuffer, b_scale_dsum_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, a_offset: u32, d_offset: u32, ) !void
    Summary: int8 DP4a full-tile single Q5_K GEMM (no fused activation).
    Description: Used by the Qwen3.6-27B SSM out prefill projection (M=hidden_dim, K=d_inner). Activations arrive pre-quantized (packed int8 + per-32-block (scale, dsum)) from recordQuantizeActQ8_1. Output is token-major f32 [N][M]. Same push/binding shape as recordMulMmQ4KFullDp4a — the only difference is the 5-bit weight unpack inside the kernel.
  - DmmvDispatch.recordMulMmQ4KFullDp4a [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q4-kfull-dp4a
    Signature: pub fn recordMulMmQ4KFullDp4a( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, b_packed_buf: vk.c.VkBuffer, b_packed_size: vk.c.VkDeviceSize, b_scale_dsum_buf: vk.c.VkBuffer, b_scale_dsum_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, a_offset: u32, d_offset: u32, accumulate: bool, ) !void
    Summary: int8 DP4a full-tile single Q4_K GEMM (no fused activation).
    Description: Used by the Qwen3.6-27B SSM z prefill projection. Activations arrive pre-quantized (packed int8 + per-32-block (scale, dsum)) from recordQuantizeActQ8_1. Output is token-major f32 [N][M].
  - DmmvDispatch.recordMulMmQ4KFullDp4aN64InterleavedAcc [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q4-kfull-dp4a-n64-interleaved-acc
    Signature: pub fn recordMulMmQ4KFullDp4aN64InterleavedAcc( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, b_packed_buf: vk.c.VkBuffer, b_packed_size: vk.c.VkDeviceSize, b_scale_dsum_buf: vk.c.VkBuffer, b_scale_dsum_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, a_offset: u32, d_offset: u32, ) !void
  - DmmvDispatch.recordMulMmQ4KTail8Dp4a [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-record-mul-mm-q4-ktail8-dp4a
    Signature: pub fn recordMulMmQ4KTail8Dp4a( self: *const DmmvDispatch, cmd: *CommandBuffer, push_desc_fn: ?PushDescriptorFn, a_buf: vk.c.VkBuffer, a_size: vk.c.VkDeviceSize, b_packed_buf: vk.c.VkBuffer, b_packed_size: vk.c.VkDeviceSize, b_scale_dsum_buf: vk.c.VkBuffer, b_scale_dsum_size: vk.c.VkDeviceSize, d_buf: vk.c.VkBuffer, d_size: vk.c.VkDeviceSize, M: u32, N: u32, K: u32, a_offset: u32, b_packed_offset: u32, b_scale_dsum_offset: u32, d_offset: u32, ) !void
    Summary: BN=8 int8 DP4a Q4_K dense-down tail for Gemma 4 31B short prompts.
    Description: Descriptor offsets select the tail token slice of the pre-quantized Q8_1 activation buffers; d_offset keeps the f32 output token-major.
  - DmmvDispatch.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/dmmv/#dmmv-dispatch-deinit
    Signature: pub fn deinit(self: *DmmvDispatch) void
    Summary: Destroy the loaded pipelines and descriptor pool.
    Param self: Dispatch wrapper to tear down in place.

### Module: Elementwise
URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/
Source: src/compute/elementwise.zig
Code lines: 996
Summary: Wrap the fused element-wise shader family used by the decode loop.
Overview: This helper loads the RMS norm, SwiGLU, and RoPE pipelines and records the push constants needed for their dispatches.

- RmsNormPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#rms-norm-push
  Signature: pub const RmsNormPush = extern struct
  Summary: Push constants for RMS norm shader.

- SwigluPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#swiglu-push
  Signature: pub const SwigluPush = extern struct
  Summary: Push constants for SwiGLU shader.

- DeinterleavePush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#deinterleave-push
  Signature: pub const DeinterleavePush = extern struct
  Summary: Push constants for deinterleave shader.

- SigmoidMulPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#sigmoid-mul-push
  Signature: pub const SigmoidMulPush = extern struct
  Summary: Push constants for sigmoid multiply shader.

- ScaleAccPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#scale-acc-push
  Signature: pub const ScaleAccPush = extern struct
  Summary: Push constants for scale-accumulate shader.

- BiasAddPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#bias-add-push
  Signature: pub const BiasAddPush = extern struct
  Summary: Push constants for bias add shader.

- RopePush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#rope-push
  Signature: pub const RopePush = extern struct
  Summary: Push constants for RoPE shader (with partial rotation / IMRoPE support).

- RopeBatchedPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#rope-batched-push
  Signature: pub const RopeBatchedPush = extern struct
  Summary: Push constants for rope_batched (multi-token prefill variant).
  Description: Layout mirrors src/shaders/rope_batched.comp.

- SsmConv1dPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#ssm-conv1d-push
  Signature: pub const SsmConv1dPush = extern struct
  Summary: Push constants for SSM conv1d + SiLU shader.

- SsmConv1dBatchedPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#ssm-conv1d-batched-push
  Signature: pub const SsmConv1dBatchedPush = extern struct
  Summary: Push constants for the batched SSM conv1d shader.

- F32DualBatchPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#f32-dual-batch-push
  Signature: pub const F32DualBatchPush = extern struct
  Summary: Push constants for batched f32 dual DMMV (SSM alpha/beta).

- SsmDeltaNetPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#ssm-delta-net-push
  Signature: pub const SsmDeltaNetPush = extern struct
  Summary: Push constants for SSM delta-net state update shader.

- SsmQkNormPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#ssm-qk-norm-push
  Signature: pub const SsmQkNormPush = extern struct
  Summary: Push constants for the SSM Q/K RMS-norm shader.
  Description: Drives the per-group normalization applied to query and key projections inside Mamba/SSM blocks.

- SsmGatedNormPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#ssm-gated-norm-push
  Signature: pub const SsmGatedNormPush = extern struct
  Summary: Push constants for SSM gated norm shader.

- SoftmaxTopkPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#softmax-topk-push
  Signature: pub const SoftmaxTopkPush = extern struct
  Summary: Push constants for softmax + top-k MoE router shader.

- RouterF32BatchPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#router-f32-batch-push
  Signature: pub const RouterF32BatchPush = extern struct
  Summary: Push constants for token-batched f32 router matvec.

- RmsNormScaleDmmvF32BatchPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#rms-norm-scale-dmmv-f32-batch-push
  Signature: pub const RmsNormScaleDmmvF32BatchPush = extern struct
  Summary: Push constants for token-batched Gemma router RMS norm + scale + f32 DMMV.

- SoftmaxTopkBatchPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#softmax-topk-batch-push
  Signature: pub const SoftmaxTopkBatchPush = extern struct
  Summary: Push constants for token-batched MoE top-k.

- MoeWeightedAccPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#moe-weighted-acc-push
  Signature: pub const MoeWeightedAccPush = extern struct
  Summary: Push constants for batched MoE weighted accumulate shader.
  Description: Sums all expert outputs at once: a[i] = sum_j(weight_j * b[j*src_stride+i]).

- MoeWeightedAccBatchPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#moe-weighted-acc-batch-push
  Signature: pub const MoeWeightedAccBatchPush = extern struct
  Summary: Push constants for the **batched** MoE weighted-accumulate shader.
  Description: Sums each token's `n_used` selected-expert outputs across a token batch in one dispatch: `a[t,i] = sum_j(weight_{t,j} * b[...])`.

- MoeWeightedAccScaledBatchPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#moe-weighted-acc-scaled-batch-push
  Signature: pub const MoeWeightedAccScaledBatchPush = extern struct
  Summary: Push constants for the Gemma batched MoE weighted-accumulate shader.
  Description: Same route-major contract as `MoeWeightedAccBatchPush`, with an extra per-expert scale offset for model-specific down-projection scales.

- SigmoidScaleAccBatchPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#sigmoid-scale-acc-batch-push
  Signature: pub const SigmoidScaleAccBatchPush = extern struct
  Summary: Push constants for the **batched** `sigmoid_scale_acc` shader.
  Description: Applies a per-token sigmoid-gated shared-expert add across a token batch: `accum[t,i] += sigmoid(gate_t) * src[t,i]`.

- KvCacheWritePush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#kv-cache-write-push
  Signature: pub const KvCacheWritePush = extern struct
  Summary: Push constants for KV cache write compute shader.

- KvCacheWriteBatchedPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#kv-cache-write-batched-push
  Signature: pub const KvCacheWriteBatchedPush = extern struct
  Summary: Push constants for batched KV cache write (prefillBatched path).
  Description: Matches src/shaders/kv_cache_write_batched.comp.

- ResidualRmsNormPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#residual-rms-norm-push
  Signature: pub const ResidualRmsNormPush = extern struct
  Summary: Push constants for fused residual-add + RMS norm (src/shaders/residual_rms_norm.comp).
  Description: One dispatch per `n_tokens` workgroups replaces a scale_accumulate → barrier → rms_norm_mul chain.

- PostNormResidualRmsNormPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#post-norm-residual-rms-norm-push
  Signature: pub const PostNormResidualRmsNormPush = extern struct
  Summary: Push constants for fused post-norm + residual-add + RMS norm (src/shaders/post_norm_residual_rms_norm.comp).
  Description: One dispatch replaces Gemma's post_attention_norm -> barrier -> residual_rms_norm sequence.

- ResidualRmsNormQuantQ8_1Push [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#residual-rms-norm-quant-q8-1-push
  Signature: pub const ResidualRmsNormQuantQ8_1Push = extern struct
  Summary: Push constants for fused residual-add + RMS norm + Q8_1 activation quantize (src/shaders/residual_rms_norm_quant_q8_1.comp).
  Description: Same residual/RMS math as ResidualRmsNormPush, but also emits packed int8 lanes + (scale, dsum) so the downstream Qwen3.6-27B dense FFN DP4a gate+up GEMM can skip its separate quantize_act_q8_1 dispatch.

- NormRopePush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#norm-rope-push
  Signature: pub const NormRopePush = extern struct
  Summary: Push constants for fused RMS norm + RoPE shader.

- RmsNormAddPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#rms-norm-add-push
  Signature: pub const RmsNormAddPush = extern struct
  Summary: Push constants for fused rmsnorm(src) + hidden accumulate shader (src/shaders/rms_norm_add.comp).
  Description: Used by Gemma prefillBatched to fold post_ffw_norm + residual add into one dispatch.

- RmsNormDmmvF32Push [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#rms-norm-dmmv-f32-push
  Signature: pub const RmsNormDmmvF32Push = extern struct
  Summary: Push constants for fused RMS norm + f32 router DMMV shader (src/shaders/rms_norm_dmmv_f32.comp).
  Description: Folds the per-MoE-layer rms_norm_mul → router DMMV pair into a single dispatch on architectures whose router weights are f32 (Qwen 3.5/3.6 etc).

- RmsNormDmmvQ4kAlphaBetaPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#rms-norm-dmmv-q4k-alpha-beta-push
  Signature: pub const RmsNormDmmvQ4kAlphaBetaPush = extern struct
  Summary: Push constants for fused RMS norm + Q4_K alpha+beta SSM proj DMMV (src/shaders/rms_norm_dmmv_q4k_alpha_beta.comp).
  Description: Folds the per-SSM-layer (rms_norm_mul → alpha DMMV → beta DMMV) trio into a single dispatch on the qwen35moe / qwen36moe SSM proj fast path.

- QkNormRopeKvWritePush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#qk-norm-rope-kv-write-push
  Signature: pub const QkNormRopeKvWritePush = extern struct
  Summary: Push constants for fused Q+K norm + RoPE + KV cache write shader (src/shaders/qk_norm_rope_kv_write.comp).
  Description: Folds the per-attention-layer (Q norm+rope → K norm+rope → kv_cache_write) trio on Qwen 3 family dense attention into a single dispatch.

- QkNormRopeKvWriteBatchedPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#qk-norm-rope-kv-write-batched-push
  Signature: pub const QkNormRopeKvWriteBatchedPush = extern struct
  Summary: Batched SWA variant of QkNormRopeKvWritePush.
  Description: Binding 4 is the KV page table, so this variant computes RoPE frequencies from freq_base_bits instead of reading a frequency buffer.

- KNormRopeKvWriteBatchedPush [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#knorm-rope-kv-write-batched-push
  Signature: pub const KNormRopeKvWriteBatchedPush = extern struct
  Summary: Batched full-attention K/V sibling used when Q must keep the precomputed RoPE frequency buffer binding.
  Description: It fuses K RMS norm, K RoPE, optional V unit norm, and paged KV cache write. Q norm/RoPE stays on the existing path.

- ElementwiseDispatch [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch
  Signature: pub const ElementwiseDispatch = struct
  Summary: Manages element-wise fused kernel pipelines.
  - ElementwiseDispatch.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch-init
    Signature: pub fn init( instance: *const Instance, shader_dir: []const u8, allocator: std.mem.Allocator, ) !ElementwiseDispatch
    Summary: Create the fused element-wise dispatch wrapper and load its shaders.
    Param instance: Active Vulkan instance and logical device.
    Param shader_dir: Directory containing compiled SPIR-V shader binaries.
    Param allocator: Allocator used for temporary pipeline creation state.
    Returns: An ElementwiseDispatch ready to record element-wise passes.
  - ElementwiseDispatch.recordRmsNorm [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch-record-rms-norm
    Signature: pub fn recordRmsNorm( self: *const ElementwiseDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, hidden_dim: u32, n_tokens: u32, eps: f32, ) !void
    Summary: Record an RMS-norm-plus-scale dispatch for a batch of tokens.
    Description: This binds the fused normalization shader used before attention and MLP projections so each token is normalized against its hidden dimension.
    Param self: Dispatch wrapper containing the RMS norm pipeline.
    Param cmd: Command buffer currently being recorded.
    Param descriptor_set: Descriptor set containing input, weight, and output buffers.
    Param hidden_dim: Hidden width processed per token.
    Param n_tokens: Number of tokens covered by the dispatch.
    Param eps: Numerical stability epsilon passed to the shader.
    Returns: `error.ShaderNotLoaded` when the RMS norm pipeline is unavailable.
    Note: The helper dispatches one workgroup per token.
  - ElementwiseDispatch.recordSwiglu [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch-record-swiglu
    Signature: pub fn recordSwiglu( self: *const ElementwiseDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, n_elements: u32, ) !void
    Summary: Record a SwiGLU activation dispatch.
    Param self: Dispatch wrapper containing the SwiGLU pipeline.
    Param cmd: Command buffer currently being recorded.
    Param descriptor_set: Descriptor set containing gate, up, and output buffers.
    Param n_elements: Total number of output elements to compute.
    Returns: `error.ShaderNotLoaded` when the SwiGLU pipeline is unavailable.
    Note: Workgroups are sized as `ceil(n_elements / 64)`.
  - ElementwiseDispatch.recordSwigluOai [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch-record-swiglu-oai
    Signature: pub fn recordSwigluOai( self: *const ElementwiseDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, n_elements: u32, ) !void
    Summary: Record a GPT-OSS / OAI-variant SwiGLU activation dispatch.
    Description: Uses the same 3-binding layout as `recordSwiglu` (gate, up → output) but selects the swiglu_oai shader whose activation function matches gpt-oss.
    Param self: Dispatch wrapper containing the OAI SwiGLU pipeline.
    Param cmd: Command buffer currently being recorded.
    Param descriptor_set: Descriptor set containing gate, up, and output buffers.
    Param n_elements: Total number of output elements to compute.
    Returns: `error.ShaderNotLoaded` when the OAI SwiGLU pipeline is unavailable.
    Note: Workgroups are sized as `ceil(n_elements / 64)`.
  - ElementwiseDispatch.recordBiasAdd [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch-record-bias-add
    Signature: pub fn recordBiasAdd( self: *const ElementwiseDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, n_elements: u32, src_offset: u32, ) !void
    Summary: Record an in-place bias add dispatch: `out[i] += bias[src_offset + i]`.
    Param self: Dispatch wrapper containing the bias add pipeline.
    Param cmd: Command buffer currently being recorded.
    Param descriptor_set: Descriptor set with two bindings: output buffer (rw) and bias buffer (ro).
    Param n_elements: Number of elements to update.
    Param src_offset: Element offset into the bias buffer (allows a shared bias tensor to be sliced).
    Returns: `error.ShaderNotLoaded` when the bias add pipeline is unavailable.
  - ElementwiseDispatch.recordGeglu [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch-record-geglu
    Signature: pub fn recordGeglu( self: *const ElementwiseDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, n_elements: u32, ) !void
    Summary: Record a GEGLU activation dispatch (GELU-gated, used by Gemma).
    Description: Same buffer layout as SwiGLU: gate, up → output.
  - ElementwiseDispatch.recordRope [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch-record-rope
    Signature: pub fn recordRope( self: *const ElementwiseDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, stride: u32, rope_dim: u32, n_heads: u32, position: u32, freq_base: f32, attn_scale: f32, ) !void
    Summary: Record a RoPE dispatch with partial rotation support (IMRoPE).
    Description: Rotates the first `rope_dim` dimensions of each attention head at the given sequence position; the remaining `stride - rope_dim` dimensions are copied unchanged, enabling interleaved-masked (IMRoPE) layouts.
    Param self: Dispatch wrapper containing the RoPE pipeline.
    Param cmd: Command buffer currently being recorded.
    Param descriptor_set: Descriptor set with three bindings: input, output, and freq buffer.
    Param stride: Full head dimension in f32 elements (distance between heads in the buffer).
    Param rope_dim: Number of dimensions to rotate (must be <= stride; pass stride for plain RoPE).
    Param n_heads: Number of query heads to rotate; one workgroup is dispatched per head.
    Param position: Current decode token position used to compute rotation angles.
    Param freq_base: Base frequency for the sinusoidal schedule (e.g. 10000.0 for standard RoPE).
    Param attn_scale: YaRN magnitude scale applied after rotation; use 1.0 for plain RoPE.
    Returns: `error.ShaderNotLoaded` when the RoPE pipeline is unavailable.
  - ElementwiseDispatch.recordRoPEBatched [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch-record-ro-pebatched
    Signature: pub fn recordRoPEBatched( self: *const ElementwiseDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, stride: u32, rope_dim: u32, n_heads: u32, position_base: u32, n_tokens: u32, freq_base: f32, attn_scale: f32, ) !void
    Summary: Record a batched RoPE dispatch that rotates N tokens at consecutive positions [position_base, position_base + n_tokens) in a single call.
    Description: Grid is (n_heads, n_tokens, 1); each (head, token) workgroup rotates `rope_dim` elements of the token's head slice.
  - ElementwiseDispatch.recordDeinterleave [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch-record-deinterleave
    Signature: pub fn recordDeinterleave( self: *const ElementwiseDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, head_dim: u32, n_heads: u32, ) !void
    Summary: Record a deinterleave dispatch: split element-interleaved Q+gate into separate buffers.
  - ElementwiseDispatch.recordDeinterleaveBatched [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch-record-deinterleave-batched
    Signature: pub fn recordDeinterleaveBatched( self: *const ElementwiseDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, head_dim: u32, n_heads: u32, n_tokens: u32, ) !void
    Summary: Record a token-batched deinterleave dispatch.
    Description: Splits each token's packed `[Q(head_dim), gate(head_dim)]` interleaved per-head layout into separate Q and gate output buffers in one dispatch. Grid is `(ceil(head_dim * n_heads / 64), n_tokens, 1)`.
    Param self: Dispatch wrapper containing the batched deinterleave pipeline.
    Param cmd: Command buffer currently being recorded.
    Param descriptor_set: Descriptor set with 3 bindings: packed input, Q output, gate output.
    Param head_dim: Per-head dimension in elements.
    Param n_heads: Number of query heads per token.
    Param n_tokens: Number of tokens to process (Y dimension of the dispatch grid).
    Returns: `error.ShaderNotLoaded` when the batched deinterleave pipeline is unavailable.
  - ElementwiseDispatch.recordSigmoidMul [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch-record-sigmoid-mul
    Signature: pub fn recordSigmoidMul( self: *const ElementwiseDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, n_elements: u32, ) !void
    Summary: Record a sigmoid multiply dispatch: out = input * sigmoid(gate).
  - ElementwiseDispatch.recordVadd [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch-record-vadd
    Signature: pub fn recordVadd( self: *const ElementwiseDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, n_elements: u32, ) !void
    Summary: Record a vector add dispatch: c = a + b.
  - ElementwiseDispatch.recordScaleAcc [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch-record-scale-acc
    Signature: pub fn recordScaleAcc( self: *const ElementwiseDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, n_elements: u32, scale: f32, ) !void
    Summary: Record a scale-accumulate dispatch: a[i] += scale * b[i].
    Description: Vec4-coalesced: each thread handles one vec4 (4 f32 elements). Caller must pass n_elements divisible by 4; every in-tree caller already does.
  - ElementwiseDispatch.recordScaleInPlace [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch-record-scale-in-place
    Signature: pub fn recordScaleInPlace( self: *const ElementwiseDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, n_elements: u32, scale: f32, ) !void
    Summary: Record an in-place element-wise scale dispatch: `data[i] *= scale`.
    Param self: Dispatch wrapper containing the scale-in-place pipeline.
    Param cmd: Command buffer currently being recorded.
    Param descriptor_set: Descriptor set with one binding: the buffer to scale in place.
    Param n_elements: Number of f32 elements to scale.
    Param scale: Scalar multiplier applied to every element.
    Returns: `error.ShaderNotLoaded` when the scale-in-place pipeline is unavailable.
  - ElementwiseDispatch.recordSsmConv1d [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch-record-ssm-conv1d
    Signature: pub fn recordSsmConv1d( self: *const ElementwiseDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, conv_channels: u32, d_conv: u32, kernel_is_f16: bool, state_offset: u32, ) !void
    Summary: Record a single-token SSM depthwise conv1d + SiLU dispatch.
    Description: Reads the current SSM conv state via `state_offset` (a rotating index into the circular state buffer), applies a depthwise conv kernel of width `d_conv`, and writes the SiLU-activated output in-place.
    Param self: Dispatch wrapper containing the SSM conv1d pipeline.
    Param cmd: Command buffer currently being recorded.
    Param descriptor_set: Descriptor set with four bindings: input, kernel, state, output.
    Param conv_channels: Number of SSM channels (width of the depthwise conv).
    Param d_conv: Kernel width of the depthwise convolution.
    Param kernel_is_f16: True when the kernel weight buffer is f16; false for f32.
    Param state_offset: Current rotation index (0..d_conv-2) into the circular state buffer.
    Returns: `error.ShaderNotLoaded` when the SSM conv1d pipeline is unavailable.
  - ElementwiseDispatch.recordSsmQkNorm [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch-record-ssm-qk-norm
    Signature: pub fn recordSsmQkNorm( self: *const ElementwiseDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, d_state: u32, n_group: u32, ) !void
    Summary: Record an in-place SSM Q/K RMS-norm dispatch.
    Description: Applies per-group RMS normalization to the concatenated Q and K projections inside a Mamba/DeltaNet SSM block; dispatches one workgroup per group.
    Param self: Dispatch wrapper containing the SSM Q/K norm pipeline.
    Param cmd: Command buffer currently being recorded.
    Param descriptor_set: Descriptor set with one binding: the Q+K buffer (in-place).
    Param d_state: Per-group state dimension (qk_dim = d_state * n_group).
    Param n_group: Number of normalization groups; one workgroup per group.
    Returns: `error.ShaderNotLoaded` when the SSM Q/K norm pipeline is unavailable.
  - ElementwiseDispatch.recordSsmDeltaNet [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch-record-ssm-delta-net
    Signature: pub fn recordSsmDeltaNet( self: *const ElementwiseDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, push: SsmDeltaNetPush, ) !void
    Summary: Record an SSM DeltaNet state-update dispatch (baseline variant).
    Description: Executes the DeltaNet recurrence over a single token (or `push.n_tok` prefill tokens when n_tok > 1). Grid is `(dt_rank, head_v_dim, 1)` — one wave64 workgroup per (head, row) pair.
    Param self: Dispatch wrapper containing the SSM delta-net pipeline.
    Param cmd: Command buffer currently being recorded.
    Param descriptor_set: Descriptor set with 7 bindings: conv_out, dt_bias, alpha, beta, ssm_a, state, output.
    Param push: Fully populated push-constant struct describing the SSM dimensions and flags.
    Returns: `error.ShaderNotLoaded` when the SSM delta-net pipeline is unavailable.
  - ElementwiseDispatch.recordSsmDeltaNetCols8 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch-record-ssm-delta-net-cols8
    Signature: pub fn recordSsmDeltaNetCols8( self: *const ElementwiseDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, push: SsmDeltaNetPush, ) !void
    Summary: Record an SSM DeltaNet state-update dispatch using the cols8 tiled variant.
    Description: Each wave64 workgroup processes four output rows (head_v_dim / 4 workgroups per head), improving register reuse relative to the baseline 1-row shader.
    Param self: Dispatch wrapper containing the SSM delta-net cols8 pipeline.
    Param cmd: Command buffer currently being recorded.
    Param descriptor_set: Descriptor set with 7 bindings (same layout as `recordSsmDeltaNet`).
    Param push: Fully populated push-constant struct describing the SSM dimensions and flags.
    Returns: `error.ShaderNotLoaded` when the SSM delta-net cols8 pipeline is unavailable.
  - ElementwiseDispatch.recordSsmDeltaNetCols8Normed [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch-record-ssm-delta-net-cols8-normed
    Signature: pub fn recordSsmDeltaNetCols8Normed( self: *const ElementwiseDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, push: SsmDeltaNetPush, ) !void
    Summary: Record an SSM DeltaNet state-update dispatch using the cols8 normed variant.
    Description: Identical semantics to `recordSsmDeltaNetCols8` but selects the shader that expects Q/K inputs to be pre-normalized (skipping the in-shader norm). Each wave64 workgroup processes eight output rows (head_v_dim / 8 workgroups per head).
    Param self: Dispatch wrapper containing the SSM delta-net cols8 normed pipeline.
    Param cmd: Command buffer currently being recorded.
    Param descriptor_set: Descriptor set with 7 bindings (same layout as `recordSsmDeltaNet`).
    Param push: Fully populated push-constant struct describing the SSM dimensions and flags.
    Returns: `error.ShaderNotLoaded` when the SSM delta-net cols8 normed pipeline is unavailable.
  - ElementwiseDispatch.recordSsmGatedNorm [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch-record-ssm-gated-norm
    Signature: pub fn recordSsmGatedNorm( self: *const ElementwiseDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, push: SsmGatedNormPush, ) !void
    Summary: Record an SSM gated norm dispatch: applies z-gate * RMS-norm(delta_output).
    Description: Dispatches one wave64 workgroup per head (`push.dt_rank` workgroups total).
    Param self: Dispatch wrapper containing the SSM gated norm pipeline.
    Param cmd: Command buffer currently being recorded.
    Param descriptor_set: Descriptor set with 4 bindings: delta_output, z_gate, norm_weights, output.
    Param push: Push-constant struct specifying d_inner, dt_rank, head_v_dim, d_state, and norm_per_head.
    Returns: `error.ShaderNotLoaded` when the SSM gated norm pipeline is unavailable.
  - ElementwiseDispatch.recordSoftmaxTopk [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch-record-softmax-topk
    Signature: pub fn recordSoftmaxTopk( self: *const ElementwiseDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, n_experts: u32, k: u32, ) !void
    Summary: Record softmax + top-k MoE router dispatch.
  - ElementwiseDispatch.recordSigmoidScaleAcc [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch-record-sigmoid-scale-acc
    Signature: pub fn recordSigmoidScaleAcc( self: *const ElementwiseDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, n_elements: u32, ) !void
    Summary: Record sigmoid-gated scale-accumulate: a[i] += sigmoid(c[0]) * b[i].
  - ElementwiseDispatch.recordMoeWeightedAcc [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch-record-moe-weighted-acc
    Signature: pub fn recordMoeWeightedAcc( self: *const ElementwiseDispatch, cmd: *CommandBuffer, descriptor_set: vk.c.VkDescriptorSet, n_elements: u32, n_used: u32, src_stride: u32, ) !void
    Summary: Record a MoE weighted accumulate dispatch: `a[i] += routing_weight[j] * b[j*src_stride + i]` summed over `n_used` selected experts.
    Description: Routing weights are read from the GPU routing buffer (binding 2), not from a push constant.
    Param self: Dispatch wrapper containing the MoE weighted accumulate pipeline.
    Param cmd: Command buffer currently being recorded.
    Param descriptor_set: Descriptor set with 3 bindings: accum (rw), src experts, routing weights.
    Param n_elements: Hidden dimension of the accumulation buffer (elements updated per token).
    Param n_used: Number of selected experts whose outputs are summed.
    Param src_stride: Elements per expert in the source buffer (typically equal to n_elements).
    Returns: `error.ShaderNotLoaded` when the MoE weighted accumulate pipeline is unavailable.
  - ElementwiseDispatch.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/elementwise/#elementwise-dispatch-deinit
    Signature: pub fn deinit(self: *ElementwiseDispatch) void
    Summary: Destroy the loaded pipelines and descriptor pool.
    Param self: Dispatch wrapper to tear down in place.

### Module: Runtime Assets
URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime-assets/
Source: src/runtime_assets.zig
Code lines: 130
Summary: Runtime asset discovery for installed and source-tree ZINC layouts.
Overview: Release archives place shader assets next to the executable under `share/zinc/shaders`, while development builds often run from the repository with assets under `zig-out` or `src/shaders`. This module centralizes that lookup and keeps backend code from hardcoding source-checkout paths.

- ShaderKind [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime-assets/#shader-kind
  Signature: pub const ShaderKind = enum
  Summary: Which compiled shader family to locate.

- resolveShaderDir [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime-assets/#resolve-shader-dir
  Signature: pub fn resolveShaderDir(allocator: std.mem.Allocator, kind: ShaderKind) ![]u8
  Summary: Resolve the directory holding compiled shaders of `kind`, honoring `ZINC_SHADER_DIR`.
  Description: Checks the `ZINC_SHADER_DIR` environment override first, then falls back to the executable-relative install layout and the in-tree development paths. or `error.ShaderDirNotFound` when no known layout exists.
  Param allocator: Allocator for the returned path; the caller owns the result.
  Param kind: Shader family to locate (SPIR-V or Metal).
  Returns: Newly allocated path to the shader directory.
  Note: Returns `error.ShaderDirOverrideNotFound` when the override is set but absent,

- resolveShaderDirFrom [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime-assets/#resolve-shader-dir-from
  Signature: pub fn resolveShaderDirFrom( allocator: std.mem.Allocator, base_dir: std.fs.Dir, exe_dir_override: ?[]const u8, kind: ShaderKind, ) ![]u8
  Summary: Resolve the shader directory against explicit base/exe dirs — the testable core of `resolveShaderDir`.
  Description: Tries the executable-relative install layout first, then the working-directory candidates for the requested shader family.
  Param allocator: Allocator for the returned path; the caller owns the result.
  Param base_dir: Directory the cwd-relative candidates are resolved against.
  Param exe_dir_override: Optional executable directory; when null the real exe path is queried.
  Param kind: Shader family to locate (SPIR-V or Metal).
  Returns: Newly allocated path to the shader directory.
  Note: Returns `error.ShaderDirNotFound` when no known layout exists.

## Hardware Detection

Vendor and architecture heuristics that translate raw Vulkan properties into tuning defaults for AMD, NVIDIA, and Intel GPUs.
URL: https://zolotukhin.ai/zinc/docs/zig-api#hardware-detection

### Module: Diagnostics Metal
URL: https://zolotukhin.ai/zinc/docs/zig-api/diagnostics-metal/
Source: src/diagnostics_metal.zig
Code lines: 665
Summary: Apple Silicon diagnostics and managed-model fit reporting for Metal.
Overview: The Metal diagnostics path inspects the default device, reports unified memory and feature support, and optionally projects how a selected GGUF or managed model fits once runtime allocations and KV reservation are included.

- Options [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/diagnostics-metal/#options
  Signature: pub const Options = struct
  Summary: Configuration for a Metal diagnostics run.

- ManagedModelInfo [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/diagnostics-metal/#managed-model-info
  Signature: pub const ManagedModelInfo = struct
  Summary: Catalog metadata for a managed (downloadable) model.

- UnifiedFitEstimate [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/diagnostics-metal/#unified-fit-estimate
  Signature: pub const UnifiedFitEstimate = struct
  Summary: Estimated unified-memory breakdown for running a model on Apple Silicon.

- run [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/diagnostics-metal/#run
  Signature: pub fn run(opts: Options, allocator: std.mem.Allocator) !void
  Summary: Run a four-step Metal preflight check (host environment, device, shader assets, model) and print a colour-coded report to stdout.
  Description: The steps are: (1) host OS and CPU arch, (2) Metal device capabilities and unified-memory budget, (3) shader source presence and MSL smoke compile, (4) GGUF or managed-model memory-fit estimate. Returns `error.DiagnosticsFailed` if any check resolves to `.fail`.
  Param opts: Diagnostic configuration: optional model path, context ceiling, managed-model entry, and shader directory.
  Param allocator: Used for Metal device initialisation and GGUF header inspection.
  Returns: `error.DiagnosticsFailed` when one or more checks emit a FAIL status; otherwise succeeds or propagates I/O errors.

- estimateUnifiedFit [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/diagnostics-metal/#estimate-unified-fit
  Signature: pub fn estimateUnifiedFit( inspection: ModelInspection, recommended_working_set_bytes: u64, total_memory_bytes: u64, requested_context_length: ?u32, ) UnifiedFitEstimate
  Summary: Compute a conservative unified-memory breakdown for running a model on Apple Silicon.
  Description: Combines tensor weight bytes with the runtime shared-buffer and KV-cache cost at the resolved context length, then determines how many tokens could fit within the Metal working-set budget.
  Param inspection: GGUF model inspection result supplying tensor size and model config.
  Param recommended_working_set_bytes: Metal driver's recommended working-set ceiling; falls back to `total_memory_bytes` when zero.
  Param total_memory_bytes: Physical unified memory on the device.
  Param requested_context_length: Optional caller-supplied context cap; when null the model's own `context_length` is used (clamped by the backend runtime cap).
  Returns: A `UnifiedFitEstimate` with per-category byte breakdowns and derived fit status fields.

### Module: Diagnostics
URL: https://zolotukhin.ai/zinc/docs/zig-api/diagnostics/
Source: src/diagnostics.zig
Code lines: 853
Summary: Vulkan system diagnostics (`zinc --check`).
Overview: Probes the host environment, Vulkan driver, GPU capabilities, shader assets, and optional GGUF model fit to produce a human-readable preflight report on stdout.

- Options [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/diagnostics/#options
  Signature: pub const Options = struct
  Summary: Configuration for a Vulkan diagnostics run.

- ManagedModelInfo [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/diagnostics/#managed-model-info
  Signature: pub const ManagedModelInfo = struct
  Summary: Catalog metadata for a managed (downloadable) model.

- FitEstimate [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/diagnostics/#fit-estimate
  Signature: pub const FitEstimate = struct
  Summary: Estimated VRAM breakdown for running a model on a discrete GPU.

- run [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/diagnostics/#run
  Signature: pub fn run(opts: Options, allocator: std.mem.Allocator) !void
  Summary: Run the five-step preflight diagnostics sequence and print a human-readable report to stdout.
  Description: Probes host OS, Vulkan driver, compiled shader assets, GPU device capabilities, and (optionally) a GGUF model file. Returns `error.DiagnosticsFailed` if any check is marked FAIL.
  Param opts: Diagnostic configuration: device index, optional model path, shader dir, etc.
  Param allocator: Used for Vulkan device enumeration and model inspection scratch space.

- estimateFit [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/diagnostics/#estimate-fit
  Signature: pub fn estimateFit(inspection: ModelInspection, vram_budget_bytes: u64, requested_context_length: ?u32) FitEstimate
  Summary: Compute a `FitEstimate` that breaks down VRAM usage for a model at a given budget.
  Description: Derives weights, KV cache, SSM state, and runtime buffer sizes from the model config and returns per-category byte counts without evaluating fit status.
  Param inspection: GGUF model inspection result supplying tensor byte count and config.
  Param vram_budget_bytes: Device-local VRAM available, as reported by the Vulkan driver.
  Param requested_context_length: Optional context ceiling override; null uses the model default.
  Returns: A `FitEstimate` with per-category byte counts and a budget-headroom context maximum.

### Module: GPU Detect
URL: https://zolotukhin.ai/zinc/docs/zig-api/gpu-detect/
Source: src/vulkan/gpu_detect.zig
Code lines: 293
Summary: Inspect the selected Vulkan device and derive architecture-specific tuning defaults.
Overview: The heuristics here convert raw Vulkan device properties into the settings used by DMMV, matmul, and attention dispatch code.

- GpuVendor [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/gpu-detect/#gpu-vendor
  Signature: pub const GpuVendor = enum
  Summary: GPU vendor and architecture buckets used by ZINC's tuning heuristics.

- GpuConfig [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/gpu-detect/#gpu-config
  Signature: pub const GpuConfig = struct
  Summary: Auto-detected GPU capabilities and derived tuning parameters.
  - GpuConfig.nameSlice [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/gpu-detect/#gpu-config-name-slice
    Signature: pub fn nameSlice(self: *const GpuConfig) []const u8
    Summary: Return the device name as a byte slice covering only the populated prefix.
    Returns: A slice of `device_name[0..device_name_len]`; no null terminator or padding included.
  - GpuConfig.log_info [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/gpu-detect/#gpu-config-log-info
    Signature: pub fn log_info(self: *const GpuConfig) void
    Summary: Log the detected GPU name, vendor, memory, wave size, cooperative-matrix support, and all derived tuning parameters at info level.

- detect [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/gpu-detect/#detect
  Signature: pub fn detect(instance: *const Instance) GpuConfig
  Summary: Inspect Vulkan device properties and derive runtime tuning defaults.
  Param instance: Active Vulkan instance whose selected physical device should be classified.
  Returns: A GpuConfig populated from Vulkan limits plus ZINC-specific vendor heuristics.
  Note: The classification is heuristic and intentionally biased toward sensible defaults rather than exact SKU detection.

## Vulkan Runtime

Low-level Vulkan setup, memory allocation, buffers, pipelines, and command submission primitives used throughout the engine.
URL: https://zolotukhin.ai/zinc/docs/zig-api#vulkan-runtime

### Module: Buffer
URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/
Source: src/vulkan/buffer.zig
Code lines: 169
Summary: Allocate Vulkan buffers used by weights, intermediates, and staging copies.
Overview: These helpers centralize buffer creation, memory mapping, and one-shot copy utilities so the rest of the runtime can work with higher-level abstractions.

- Buffer [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#buffer
  Signature: pub const Buffer = struct
  Summary: Vulkan buffer allocation paired with its device memory and optional mapped pointer.
  - Buffer.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#buffer-init
    Signature: pub fn init( instance: *const Instance, size: vk.c.VkDeviceSize, usage: vk.c.VkBufferUsageFlags, mem_properties: vk.c.VkMemoryPropertyFlags, ) !Buffer
    Summary: Create a Vulkan buffer and allocate backing device memory for it.
    Param instance: Active Vulkan instance and logical device.
    Param size: Buffer size in bytes.
    Param usage: Vulkan buffer usage flags.
    Param mem_properties: Required Vulkan memory property flags for the allocation.
    Returns: A Buffer with memory bound but not automatically mapped.
    Note: Use `initStaging()` when you need an immediately mapped upload buffer.
  - Buffer.initDeviceLocal [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#buffer-init-device-local
    Signature: pub fn initDeviceLocal(instance: *const Instance, size: vk.c.VkDeviceSize, usage: vk.c.VkBufferUsageFlags) !Buffer
    Summary: Create a device-local buffer for GPU-only reads and writes.
    Param instance: Active Vulkan instance and logical device.
    Param size: Buffer size in bytes.
    Param usage: Additional Vulkan usage flags for the buffer.
    Returns: A device-local buffer with transfer-destination usage enabled.
    Note: This helper automatically adds `VK_BUFFER_USAGE_TRANSFER_DST_BIT` for staging uploads.
  - Buffer.initStaging [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#buffer-init-staging
    Signature: pub fn initStaging(instance: *const Instance, size: vk.c.VkDeviceSize) !Buffer
    Summary: Create and immediately map a host-visible staging buffer.
    Param instance: Active Vulkan instance and logical device.
    Param size: Buffer size in bytes.
    Returns: A staging buffer ready for CPU writes through `mapped`.
    Note: The buffer uses coherent host memory so writes do not require an explicit flush.
  - Buffer.initHostVisibleStorage [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#buffer-init-host-visible-storage
    Signature: pub fn initHostVisibleStorage(instance: *const Instance, size: vk.c.VkDeviceSize) !Buffer
    Summary: Create a host-visible storage buffer that the GPU reads in place via PCIe.
    Description: it over PCIe BAR rather than from device-local VRAM. Used to offload large rarely-touched tensors (MoE expert weights) when device memory is insufficient. Coherent memory means no explicit invalidate is needed; we only write at load time.
    Param instance: Active Vulkan instance and logical device.
    Param size: Buffer size in bytes.
    Returns: A storage buffer ready for direct CPU writes through `mapped`.
    Note: Memory is allocated as `HOST_VISIBLE | HOST_COHERENT`, so the GPU reads
  - Buffer.upload [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#buffer-upload
    Signature: pub fn upload(self: *const Buffer, data: []const u8) void
    Summary: Copy raw bytes into a previously mapped buffer (staging or host-visible storage).
    Param self: Buffer whose `mapped` pointer is non-null.
    Param data: Bytes to copy from the CPU into the mapped range.
    Note: Asserts at debug time that the buffer is mapped and `data` fits within the allocation.
  - Buffer.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#buffer-deinit
    Signature: pub fn deinit(self: *Buffer) void
    Summary: Destroy the Vulkan buffer, free device memory, and unmap any host-mapped pointer.
    Param self: Buffer to tear down; the struct fields are set to `undefined` on return.

- copyBuffer [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#copy-buffer
  Signature: pub fn copyBuffer( instance: *const Instance, cmd_pool: vk.c.VkCommandPool, src: *const Buffer, dst: *const Buffer, size: vk.c.VkDeviceSize, ) !void
  Summary: Copy bytes between two Vulkan buffers with a temporary one-shot command buffer.
  Param instance: Active Vulkan instance and logical device.
  Param cmd_pool: Command pool used to allocate the temporary command buffer.
  Param src: Source buffer.
  Param dst: Destination buffer.
  Param size: Number of bytes to copy.
  Returns: `error.AllocCmdBufFailed` or `error.QueueSubmitFailed` when command allocation or submission fails.
  Note: This helper waits for the compute queue to go idle before returning.

### Module: Command
URL: https://zolotukhin.ai/zinc/docs/zig-api/command/
Source: src/vulkan/command.zig
Code lines: 496
Summary: Create reusable compute command pools and command buffers.
Overview: The decode runtime uses these wrappers to record dispatches, insert barriers, and synchronize submitted compute work.

- CommandPool [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-pool
  Signature: pub const CommandPool = struct
  Summary: Command pool for allocating command buffers.
  - CommandPool.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-pool-init
    Signature: pub fn init(instance: *const Instance) !CommandPool
    Summary: Create a command pool bound to the selected compute queue family.
    Param instance: Active Vulkan instance and logical device.
    Returns: A CommandPool ready to allocate compute command buffers.
  - CommandPool.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-pool-deinit
    Signature: pub fn deinit(self: *CommandPool) void
    Summary: Destroy the underlying Vulkan command pool.
    Param self: Command pool to tear down in place.

- CommandBuffer [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-buffer
  Signature: pub const CommandBuffer = struct
  Summary: A recorded command buffer that can be submitted and replayed.
  - CommandBuffer.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-buffer-init
    Signature: pub fn init(instance: *const Instance, pool: *const CommandPool) !CommandBuffer
    Summary: Allocate a primary command buffer and fence from a compute command pool.
    Param instance: Active Vulkan instance and logical device.
    Param pool: Command pool used for command buffer allocation.
    Returns: A CommandBuffer paired with a completion fence.
  - CommandBuffer.begin [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-buffer-begin
    Signature: pub fn begin(self: *CommandBuffer) !void
    Summary: Begin recording a reusable command buffer.
    Param self: Command buffer to begin recording into.
    Returns: `error.BeginCommandBufferFailed` when Vulkan rejects the begin request.
    Note: Use `reset()` or wait for prior submissions before recording into the same buffer again.
  - CommandBuffer.beginOneTime [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-buffer-begin-one-time
    Signature: pub fn beginOneTime(self: *CommandBuffer) !void
    Summary: Begin recording for a single submit-and-discard style workload.
    Param self: Command buffer to begin recording into.
    Returns: `error.BeginCommandBufferFailed` when Vulkan rejects the begin request.
    Note: This sets `VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT` so the driver can optimize transient work.
  - CommandBuffer.dispatch [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-buffer-dispatch
    Signature: pub fn dispatch( self: *CommandBuffer, pipeline: *const Pipeline, descriptor_set: vk.c.VkDescriptorSet, group_count_x: u32, group_count_y: u32, group_count_z: u32, ) void
    Summary: Record a compute dispatch with an already-created descriptor set.
    Param self: Command buffer currently being recorded.
    Param pipeline: Compute pipeline to bind before dispatch.
    Param descriptor_set: Descriptor set bound at set `0`.
    Param group_count_x: Workgroup count in the X dimension.
    Param group_count_y: Workgroup count in the Y dimension.
    Param group_count_z: Workgroup count in the Z dimension.
    Note: This helper binds pipeline and descriptors only; required barriers must be recorded separately.
  - CommandBuffer.dispatchWithPush [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-buffer-dispatch-with-push
    Signature: pub fn dispatchWithPush( self: *CommandBuffer, pipeline: *const Pipeline, descriptor_set: vk.c.VkDescriptorSet, push_data: []const u8, group_count_x: u32, group_count_y: u32, group_count_z: u32, ) void
    Summary: Record a compute dispatch that also uploads a serialized push-constant block.
    Param self: Command buffer currently being recorded.
    Param pipeline: Compute pipeline to bind before dispatch.
    Param descriptor_set: Descriptor set bound at set `0`.
    Param push_data: Raw bytes copied into the pipeline's push-constant range at offset `0`.
    Param group_count_x: Workgroup count in the X dimension.
    Param group_count_y: Workgroup count in the Y dimension.
    Param group_count_z: Workgroup count in the Z dimension.
    Note: The caller is responsible for matching `push_data` to the shader layout declared by `pipeline`.
  - CommandBuffer.pushDescAndDispatch [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-buffer-push-desc-and-dispatch
    Signature: pub fn pushDescAndDispatch( self: *CommandBuffer, pipeline: *const Pipeline, push_desc_fn: ?PushDescriptorFn, buffer_infos: []const vk.c.VkDescriptorBufferInfo, push_data: []const u8, group_count_x: u32, group_count_y: u32, group_count_z: u32, ) void
    Summary: Record a compute dispatch using `VK_KHR_push_descriptor`.
    Param self: Command buffer currently being recorded.
    Param pipeline: Compute pipeline whose set-0 layout was created for push descriptors.
    Param push_desc_fn: Loaded `vkCmdPushDescriptorSetKHR` function pointer.
    Param buffer_infos: Storage-buffer bindings to push into set `0`; at most 8 entries.
    Param push_data: Raw bytes copied into the pipeline's push-constant range at offset `0`; may be empty.
    Param group_count_x: Workgroup count in the X dimension.
    Param group_count_y: Workgroup count in the Y dimension.
    Param group_count_z: Workgroup count in the Z dimension.
    Note: Asserts that `push_desc_fn` is non-null and `buffer_infos.len <= 8`.
  - CommandBuffer.pushDescAndDispatchIndirect [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-buffer-push-desc-and-dispatch-indirect
    Signature: pub fn pushDescAndDispatchIndirect( self: *CommandBuffer, pipeline: *const Pipeline, push_desc_fn: ?PushDescriptorFn, buffer_infos: []const vk.c.VkDescriptorBufferInfo, push_data: []const u8, indirect_buffer: vk.c.VkBuffer, indirect_offset: vk.c.VkDeviceSize, ) void
    Summary: Record a push-descriptor compute dispatch whose group counts are read from a device buffer.
    Description: The indirect buffer must contain a `VkDispatchIndirectCommand` at the given byte offset.
    Param self: Command buffer currently being recorded.
    Param pipeline: Compute pipeline whose set-0 layout was created for push descriptors.
    Param push_desc_fn: Loaded `vkCmdPushDescriptorSetKHR` function pointer.
    Param buffer_infos: Storage-buffer bindings to push into set `0`; at most 8 entries.
    Param push_data: Raw bytes copied into the pipeline's push-constant range at offset `0`; may be empty.
    Param indirect_buffer: Device buffer containing the `VkDispatchIndirectCommand` group counts.
    Param indirect_offset: Byte offset into `indirect_buffer` where the command struct begins.
    Note: Asserts that `push_desc_fn` is non-null and `buffer_infos.len <= 8`.
  - CommandBuffer.computeBufferBarrier [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-buffer-compute-buffer-barrier
    Signature: pub fn computeBufferBarrier(self: *const CommandBuffer, buffer: vk.c.VkBuffer, size: vk.c.VkDeviceSize) void
    Summary: Insert a buffer-specific compute barrier (only synchronizes the given buffer).
    Description: May allow the driver to avoid flushing unrelated caches.
  - CommandBuffer.computeToIndirectBufferBarrier [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-buffer-compute-to-indirect-buffer-barrier
    Signature: pub fn computeToIndirectBufferBarrier(self: *const CommandBuffer, buffer: vk.c.VkBuffer, size: vk.c.VkDeviceSize) void
    Summary: Insert a compute-shader-write to indirect-command-read barrier.
    Description: Needed when a shader writes VkDispatchIndirectCommand records consumed by vkCmdDispatchIndirect later in the same command buffer.
  - CommandBuffer.computeBuffersBarrier [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-buffer-compute-buffers-barrier
    Signature: pub fn computeBuffersBarrier(self: *const CommandBuffer, ranges: []const BufferRange) void
    Summary: Insert a multi-buffer compute barrier covering several specific buffer ranges in one vkCmdPipelineBarrier call.
    Description: Lets the driver flush only the named buffer caches instead of a global memory barrier — when downstream ops only depend on a known subset of pending writes, unrelated in-flight writes can keep flowing. Up to 8 ranges supported in the inline buffer; larger calls fall back to global.
  - CommandBuffer.computeBarrier [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-buffer-compute-barrier
    Signature: pub fn computeBarrier(self: *const CommandBuffer) void
    Summary: Insert a compute-to-compute pipeline barrier (shader write → shader read).
    Param self: Command buffer currently being recorded.
    Note: Uses a coarse global memory barrier; prefer buffer barriers for fine-grained sync.
  - CommandBuffer.computeToTransferBarrier [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-buffer-compute-to-transfer-barrier
    Signature: pub fn computeToTransferBarrier(self: *const CommandBuffer) void
    Summary: Insert a compute-to-transfer pipeline barrier (shader write → transfer read/write).
    Param self: Command buffer currently being recorded.
    Note: Use this before copying from or into buffers produced by compute shaders.
  - CommandBuffer.transferToComputeBarrier [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-buffer-transfer-to-compute-barrier
    Signature: pub fn transferToComputeBarrier(self: *const CommandBuffer) void
    Summary: Insert a transfer-to-compute pipeline barrier (copy/upload → shader read).
    Param self: Command buffer currently being recorded.
    Note: Ensures prior transfer writes are visible before subsequent compute dispatches.
  - CommandBuffer.computeAndTransferBarrier [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-buffer-compute-and-transfer-barrier
    Signature: pub fn computeAndTransferBarrier(self: *const CommandBuffer) void
    Summary: Insert a combined compute→compute+transfer barrier.
    Description: Shader writes become visible to both subsequent compute dispatches and transfer reads. Use when compute output feeds both a shader read and a buffer copy in the same stage.
  - CommandBuffer.transferToTransferBarrier [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-buffer-transfer-to-transfer-barrier
    Signature: pub fn transferToTransferBarrier(self: *const CommandBuffer) void
    Summary: Insert a transfer→transfer pipeline barrier (copy write → copy read).
    Description: by another vkCmdCopyBuffer in the same or a subsequent command buffer, and the caller wants strict-spec memory visibility without relying on implicit same-queue ordering semantics. This is the cross-CB safety net for effort-6 cycle 7's layer-0 stash buffers.
    Param self: Command buffer currently being recorded.
    Note: Needed when a vkCmdCopyBuffer writes a buffer whose contents are read
  - CommandBuffer.end [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-buffer-end
    Signature: pub fn end(self: *const CommandBuffer) !void
    Summary: Finalize command recording so the buffer can be submitted.
    Param self: Command buffer to finalize.
    Returns: `error.EndCommandBufferFailed` when Vulkan rejects the recorded command stream.
  - CommandBuffer.submitAndWait [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-buffer-submit-and-wait
    Signature: pub fn submitAndWait(self: *const CommandBuffer, queue: vk.c.VkQueue) !void
    Summary: Submit the command buffer and block until the GPU signals completion.
    Param self: Recorded command buffer to submit.
    Param queue: Queue to submit the work on.
    Returns: `error.QueueSubmitFailed` or `error.FenceWaitFailed` when submission or synchronization fails.
    Note: The fence is reset before returning so the command buffer can be reused by a later step.
  - CommandBuffer.submit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-buffer-submit
    Signature: pub fn submit(self: *const CommandBuffer, queue: vk.c.VkQueue) !void
    Summary: Submit recorded work and return immediately.
    Param self: Recorded command buffer to submit.
    Param queue: Queue to submit the work on.
    Returns: `error.QueueSubmitFailed` when Vulkan rejects the submission.
    Note: Pair this with `waitForCompletion()` before resetting or re-recording the command buffer.
  - CommandBuffer.waitForCompletion [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-buffer-wait-for-completion
    Signature: pub fn waitForCompletion(self: *const CommandBuffer) !void
    Summary: Wait for the command buffer's fence to signal and then reset it.
    Param self: Command buffer whose most recent submission should complete before returning.
    Returns: `error.FenceWaitFailed` when the wait operation fails.
    Note: After this returns, the command buffer can be reset and recorded again.
  - CommandBuffer.reset [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-buffer-reset
    Signature: pub fn reset(self: *const CommandBuffer) !void
    Summary: Reset the command buffer so new commands can be recorded into it.
    Param self: Command buffer to reset.
    Returns: `error.ResetCommandBufferFailed` when Vulkan rejects the reset request.
    Note: The caller must ensure the previous submission has completed before calling this.
  - CommandBuffer.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-buffer-deinit
    Signature: pub fn deinit(self: *CommandBuffer, pool: *const CommandPool) void
    Summary: Destroy the command buffer fence and free the command buffer back to its pool.
    Param self: Command buffer to tear down in place.
    Param pool: Command pool that owns the Vulkan command buffer allocation.
    Note: Callers should ensure the GPU is no longer using the buffer before teardown.

### Module: Instance
URL: https://zolotukhin.ai/zinc/docs/zig-api/instance/
Source: src/vulkan/instance.zig
Code lines: 428
Summary: Initialize Vulkan, select a compute-capable device, and expose memory utilities.
Overview: This is the entry point for GPU setup: instance creation, device selection, queue discovery, and VRAM inspection.

- auto_select_device_index [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/instance/#auto-select-device-index
  Signature: pub const auto_select_device_index: u32 = std.math.maxInt(u32)
  Summary: Sentinel passed by callers that want ZINC to choose the best Vulkan device.
  Description: Explicit CLI `-d/--device` values are still honored exactly.

- PushDescriptorFn [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/instance/#push-descriptor-fn
  Signature: pub const PushDescriptorFn = *const fn ( vk.c.VkCommandBuffer, vk.c.VkPipelineBindPoint, vk.c.VkPipelineLayout, u32, u32, [*]const vk.c.VkWriteDescriptorSet, ) callconv(.c) void
  Summary: Function pointer type for `vkCmdPushDescriptorSetKHR` when the extension is enabled.

- DeviceCapabilities [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/instance/#device-capabilities
  Signature: pub const DeviceCapabilities = struct
  Summary: Queried Vulkan device capabilities that affect pipeline creation choices.
  - DeviceCapabilities.supportsRequiredSubgroupSize [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/instance/#device-capabilities-supports-required-subgroup-size
    Signature: pub fn supportsRequiredSubgroupSize(self: DeviceCapabilities, size: u32) bool
    Summary: Return whether a compute shader can request the given subgroup size at pipeline creation.
    Param size: Desired subgroup width to validate against the device's min/max range.
    Returns: `true` when subgroup size control is enabled, `size` is within the supported range, and the compute stage supports `requiredSubgroupSize`.

- selectPhysicalDeviceIndex [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/instance/#select-physical-device-index
  Signature: pub fn selectPhysicalDeviceIndex( allocator: std.mem.Allocator, phys_devices: []const vk.c.VkPhysicalDevice, dev_count: u32, preferred_device: u32, ) !u32
  Summary: Resolve a Vulkan physical-device index.
  Description: Explicit device indices are honored exactly. The auto path avoids the common mixed-AMD trap where Mesa enumerates an APU/iGPU as device 0 and the discrete RDNA card as device 1.

- Instance [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/instance/#instance
  Signature: pub const Instance = struct
  Summary: Active Vulkan instance, selected physical device, logical device, and memory metadata.
  - Instance.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/instance/#instance-init
    Signature: pub fn init(allocator: std.mem.Allocator, preferred_device: u32) !Instance
    Summary: Create a Vulkan instance and select a compute-capable device.
    Param allocator: Allocator used for device and queue enumeration and stored for the lifetime of the instance.
    Param preferred_device: Preferred physical device index when multiple GPUs are present.
    Returns: An initialized Instance bound to a logical device and compute queue.
  - Instance.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/instance/#instance-deinit
    Signature: pub fn deinit(self: *Instance) void
    Summary: Wait for outstanding work, destroy the logical device, and destroy the Vulkan instance.
    Param self: Vulkan instance wrapper to tear down in place.
  - Instance.findMemoryType [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/instance/#instance-find-memory-type
    Signature: pub fn findMemoryType(self: *const Instance, type_filter: u32, properties: vk.c.VkMemoryPropertyFlags) ?u32
    Summary: Find a Vulkan memory type that satisfies both compatibility and property requirements.
    Param self: Active Vulkan instance and memory properties.
    Param type_filter: Bitmask of compatible memory types reported by Vulkan.
    Param properties: Required Vulkan memory property flags.
    Returns: The matching memory type index, or `null` when no memory type satisfies the request.
    Note: All requested property bits must be present on the returned memory type.
  - Instance.vramBytes [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/instance/#instance-vram-bytes
    Signature: pub fn vramBytes(self: *const Instance) u64
    Summary: Sum the size of all device-local memory heaps exposed by the selected GPU.
    Param self: Active Vulkan instance and memory properties.
    Returns: The total number of bytes in device-local heaps.
    Note: Drivers may expose multiple heaps, so this is an aggregate capacity rather than a single contiguous pool.

### Module: Pipeline
URL: https://zolotukhin.ai/zinc/docs/zig-api/pipeline/
Source: src/vulkan/pipeline.zig
Code lines: 201
Summary: Load SPIR-V compute shaders into Vulkan pipelines.
Overview: Dispatch helpers use this module to build descriptor layouts, pipeline layouts, and compute pipelines from the compiled shader binaries.

- Pipeline [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/pipeline/#pipeline
  Signature: pub const Pipeline = struct
  Summary: A compute pipeline wrapping a SPIR-V shader module.
  - Pipeline.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/pipeline/#pipeline-deinit
    Signature: pub fn deinit(self: *Pipeline) void
    Summary: Destroy the shader module, descriptor layout, pipeline layout, and pipeline.
    Param self: Pipeline object to tear down in place.

- SpecConst [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/pipeline/#spec-const
  Signature: pub const SpecConst = struct
  Summary: Specialization constant entry for compute pipelines.

- PipelineOptions [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/pipeline/#pipeline-options
  Signature: pub const PipelineOptions = struct
  Summary: Optional compute-pipeline knobs for subgroup-sensitive shaders.

- createFromSpirv [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/pipeline/#create-from-spirv
  Signature: pub fn createFromSpirv( instance: *const Instance, spirv_path: []const u8, binding_count: u32, push_constant_size: u32, spec_constants: []const SpecConst, allocator: std.mem.Allocator, ) !Pipeline
  Summary: Create a compute pipeline from a SPIR-V file.
  Param instance: Active Vulkan instance and logical device.
  Param spirv_path: Filesystem path to the compiled SPIR-V module.
  Param binding_count: Number of storage-buffer bindings expected by the shader.
  Param push_constant_size: Size of the push-constant block in bytes.
  Param spec_constants: Specialization constants applied at pipeline creation time.
  Param allocator: Allocator used for shader bytes and temporary Vulkan structs.
  Returns: A fully created compute pipeline and its associated layouts.

- createFromSpirvWithOptions [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/pipeline/#create-from-spirv-with-options
  Signature: pub fn createFromSpirvWithOptions( instance: *const Instance, spirv_path: []const u8, binding_count: u32, push_constant_size: u32, spec_constants: []const SpecConst, options: PipelineOptions, allocator: std.mem.Allocator, ) !Pipeline
  Summary: Create a compute pipeline from a SPIR-V file with optional subgroup and push-descriptor controls.
  Description: Reads the SPIR-V binary from disk, creates a shader module, builds a descriptor set layout (optionally flagged for push-descriptor recording), a pipeline layout with push constants, and a compute pipeline with specialization constants applied. Subgroup-size and full-subgroup requirements are silently dropped when the device does not support them.
  Param instance: Active Vulkan instance providing the logical device and capability info.
  Param spirv_path: Filesystem path to the compiled SPIR-V module.
  Param binding_count: Number of storage-buffer descriptor bindings declared by the shader.
  Param push_constant_size: Size of the push-constant block in bytes; pass 0 for none.
  Param spec_constants: Specialization constants applied at pipeline creation time.
  Param options: Optional subgroup and push-descriptor knobs; use `.{}` for defaults.
  Param allocator: Allocator used for shader bytes and temporary Vulkan structs; freed before return.
  Returns: A fully created `Pipeline` with all Vulkan objects owned by the caller.

### Module: Tooling
URL: https://zolotukhin.ai/zinc/docs/zig-api/tooling/
Source: src/vulkan/tooling.zig
Code lines: 6
Summary: Standalone Vulkan validation-tool imports.
Overview: This module is intentionally small: tools under `tools/` use it as an umbrella module when they need to exercise shader pipelines outside the main ZINC binary.

- vk [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tooling/#vk
  Signature: pub const vk = @import("vk.zig")

- instance [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tooling/#instance
  Signature: pub const instance = @import("instance.zig")

- Instance [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tooling/#instance
  Signature: pub const Instance = instance.Instance

- Buffer [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tooling/#buffer
  Signature: pub const Buffer = @import("buffer.zig").Buffer

- command [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tooling/#command
  Signature: pub const command = @import("command.zig")

- pipeline [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tooling/#pipeline
  Signature: pub const pipeline = @import("pipeline.zig")

## Metal Runtime

Low-level Metal device discovery, buffers, pipelines, and command submission primitives used by the Apple Silicon backend.
URL: https://zolotukhin.ai/zinc/docs/zig-api#metal-runtime

### Module: Buffer
URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/
Source: src/metal/buffer.zig
Code lines: 160
Summary: Metal buffer wrapper — shared-mode GPU buffers with zero-copy mmap support.
Overview: The Metal backend allocates shared-storage buffers so CPU code, the model loader, and GPU kernels can all see the same memory without an explicit staging copy. This module owns that wrapper and its mmap integration.

- MetalBuffer [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#metal-buffer
  Signature: pub const MetalBuffer = struct
  Summary: Metal buffer handle plus CPU visibility metadata used throughout the backend.
  - MetalBuffer.contents [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#metal-buffer-contents
    Signature: pub fn contents(self: *const MetalBuffer) ?[*]u8
    Summary: Return the raw CPU-visible pointer for shared-mode buffers.
  - MetalBuffer.mapped [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#metal-buffer-mapped
    Signature: pub fn mapped(self: *const MetalBuffer) ?[*]u8
    Summary: Mapped pointer alias kept for compatibility with the Vulkan buffer interface pattern.

- createBuffer [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#create-buffer
  Signature: pub fn createBuffer(ctx: ?*shim.MetalCtx, size: usize) !MetalBuffer
  Summary: Allocate a shared-storage Metal buffer that is visible to both CPU and GPU code.

- createPrivateBuffer [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#create-private-buffer
  Signature: pub fn createPrivateBuffer(ctx: ?*shim.MetalCtx, size: usize) !MetalBuffer
  Summary: Allocate a GPU-private Metal buffer without a CPU mapping.

- wrapMmap [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#wrap-mmap
  Signature: pub fn wrapMmap(ctx: ?*shim.MetalCtx, ptr: [*]u8, size: usize) !MetalBuffer
  Summary: Wrap an existing mmap region as a Metal buffer without copying its contents.

- aliasBuffer [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#alias-buffer
  Signature: pub fn aliasBuffer(base: *const MetalBuffer, offset: usize, size: usize) MetalBuffer
  Summary: Create a lightweight view into an existing buffer.
  Description: The returned handle is not retained and must not be freed independently of the owner.

- freeBuffer [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#free-buffer
  Signature: pub fn freeBuffer(buf: *MetalBuffer) void
  Summary: Free a Metal buffer handle and clear it from the wrapper.

### Module: C
URL: https://zolotukhin.ai/zinc/docs/zig-api/c/
Source: src/metal/c.zig
Code lines: 1
Summary: Shared C import for the Metal shim — all Metal modules import from here to ensure type identity across compilation units.
Overview: Keeping the `@cImport` in one place avoids duplicate opaque C types across Zig compilation units, which is critical for safely passing shim handles between the Metal device, buffer, pipeline, and command helpers.

- shim [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/c/#shim
  Signature: pub const shim = @cImport(@cInclude("shim.h"))
  Summary: Raw Metal shim C bindings imported from the Objective-C bridge header.

### Module: Command
URL: https://zolotukhin.ai/zinc/docs/zig-api/command/
Source: src/metal/command.zig
Code lines: 410
Summary: Metal command buffer wrapper — dispatch recording and GPU synchronization.
Overview: This module is the low-level bridge between ZINC's compute dispatchers and the Objective-C Metal shim. It records compute work, barriers, and timing mode so higher-level inference code can stay backend-agnostic.

- CommandEncoderMode [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#command-encoder-mode
  Signature: pub const CommandEncoderMode = enum(u8)
  Summary: Encoder policy used when opening a Metal compute command buffer.

- MetalCommand [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#metal-command
  Signature: pub const MetalCommand = struct
  Summary: A recorded command buffer that encodes compute dispatches for the GPU.
  - MetalCommand.setTimingLabel [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#metal-command-set-timing-label
    Signature: pub fn setTimingLabel(self: *MetalCommand, label: []const u8) void
    Summary: Attach a one-dispatch timing label consumed by `ZINC_METAL_KERNEL_TIMING`.
    Description: The timing aggregator copies the bytes before this label can go stale.
  - MetalCommand.clearTimingLabel [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#metal-command-clear-timing-label
    Signature: pub fn clearTimingLabel(self: *MetalCommand) void
  - MetalCommand.dispatch [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#metal-command-dispatch
    Signature: pub fn dispatch( self: *MetalCommand, pipe: *const MetalPipeline, grid: [3]u32, block: [3]u32, bufs: []const *const MetalBuffer, push_data: ?*const anyopaque, push_size: usize, ) void
    Summary: Encode a compute dispatch binding buffers, push constants, grid, and block sizes.
  - MetalCommand.dispatchV2 [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#metal-command-dispatch-v2
    Signature: pub fn dispatchV2( self: *MetalCommand, pipe: *const MetalPipeline, grid: [3]u32, block: [3]u32, bufs: []const *const MetalBuffer, push_data: ?*const anyopaque, push_size: usize, push_idx: u32, ) void
    Summary: Dispatch with explicit push constant buffer index.
    Description: SPIRV-Cross compiled shaders place push constants at a specific buffer index (often 0 or 1). Data buffers in `bufs` are bound at all other indices in order, skipping push_idx.
  - MetalCommand.dispatchV2WithTgMem [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#metal-command-dispatch-v2-with-tg-mem
    Signature: pub fn dispatchV2WithTgMem( self: *MetalCommand, pipe: *const MetalPipeline, grid: [3]u32, block: [3]u32, bufs: []const *const MetalBuffer, push_data: ?*const anyopaque, push_size: usize, push_idx: u32, tg_mem_size: u32, ) void
    Summary: Dispatch with explicit threadgroup memory allocation.
  - MetalCommand.barrier [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#metal-command-barrier
    Signature: pub fn barrier(self: *MetalCommand) void
    Summary: Insert a memory barrier ensuring all prior dispatches complete before subsequent ones.
  - MetalCommand.barrierBuffers [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#metal-command-barrier-buffers
    Signature: pub fn barrierBuffers(self: *MetalCommand, bufs: []const *const MetalBuffer) void
    Summary: Insert a resource-scoped memory barrier for the listed buffers.
  - MetalCommand.barrierResourceBuffers [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#metal-command-barrier-resource-buffers
    Signature: pub fn barrierResourceBuffers(self: *MetalCommand, bufs: []const *const MetalBuffer) void
    Summary: Insert a true resource-scoped barrier.
    Description: Use only when later work depends on the listed buffers and independent prior dispatches should stay free to overlap on a concurrent encoder.
  - MetalCommand.commitAndWait [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#metal-command-commit-and-wait
    Signature: pub fn commitAndWait(self: *MetalCommand) void
    Summary: Commit the command buffer to the GPU and block until execution completes.
  - MetalCommand.commitAsync [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#metal-command-commit-async
    Signature: pub fn commitAsync(self: *MetalCommand) void
    Summary: Commit the command buffer for async GPU execution; call `wait` later to synchronize.
  - MetalCommand.wait [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#metal-command-wait
    Signature: pub fn wait(self: *MetalCommand) void
    Summary: Block until an async-committed command buffer finishes execution.
  - MetalCommand.waitGpuDurationNs [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#metal-command-wait-gpu-duration-ns
    Signature: pub fn waitGpuDurationNs(self: *MetalCommand) u64
    Summary: Wait for completion and return Metal's GPU execution duration.
  - MetalCommand.releaseCompleted [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#metal-command-release-completed
    Signature: pub fn releaseCompleted(self: *MetalCommand) void
    Summary: Release an async command buffer that is known to be completed by a later queue-ordered wait.
    Description: The shim falls back to waiting if it is still pending.
  - MetalCommand.gpuDurationNs [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#metal-command-gpu-duration-ns
    Signature: pub fn gpuDurationNs(self: *const MetalCommand) u64
    Summary: Return Metal-reported GPU execution time for a completed async command.

- beginCommand [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#begin-command
  Signature: pub fn beginCommand(ctx: ?*shim.MetalCtx) !MetalCommand
  Summary: Allocate a new command buffer from the given Metal context.

- beginCommandWithMode [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#begin-command-with-mode
  Signature: pub fn beginCommandWithMode(ctx: ?*shim.MetalCtx, mode: CommandEncoderMode) !MetalCommand
  Summary: Allocate a command buffer using the requested encoder/barrier policy.

### Module: Device
URL: https://zolotukhin.ai/zinc/docs/zig-api/device/
Source: src/metal/device.zig
Code lines: 122
Summary: Metal device wrapper — macOS Apple Silicon GPU backend.
Overview: This module owns Metal device initialization and capability queries used by the loader, diagnostics, and Metal inference runtime.

- GpuFamily [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#gpu-family
  Signature: pub const GpuFamily = enum(u32)
  Summary: Public Apple GPU family buckets exposed by the Metal shim.
  - GpuFamily.isApple9OrNewer [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#gpu-family-is-apple9-or-newer
    Signature: pub fn isApple9OrNewer(self: @This()) bool
    Summary: Return whether the device is Apple9-class or newer.
  - GpuFamily.isM5Class [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#gpu-family-is-m5-class
    Signature: pub fn isM5Class(self: @This()) bool
    Summary: Return whether the device should be treated as M5-class for tuning.

- MetalCapabilities [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#metal-capabilities
  Signature: pub const MetalCapabilities = struct
  Summary: Capability snapshot queried once from the active Metal device.

- MetalDevice [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#metal-device
  Signature: pub const MetalDevice = struct
  Summary: Active Metal device wrapper plus capability metadata used by the backend.
  - MetalDevice.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#metal-device-init
    Signature: pub fn init(allocator: std.mem.Allocator, _: u32) !MetalDevice
    Summary: Initialize the system-default Metal device and query its public capabilities.
  - MetalDevice.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#metal-device-deinit
    Signature: pub fn deinit(self: *MetalDevice) void
    Summary: Destroy the active Metal device context.
  - MetalDevice.maxBufferSize [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#metal-device-max-buffer-size
    Signature: pub fn maxBufferSize(self: *const MetalDevice) u64
    Summary: Return the largest single Metal buffer size reported by the driver.
  - MetalDevice.totalMemory [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#metal-device-total-memory
    Signature: pub fn totalMemory(self: *const MetalDevice) u64
    Summary: Return the total unified memory size reported for the active device.
  - MetalDevice.recommendedMaxWorkingSetSize [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#metal-device-recommended-max-working-set-size
    Signature: pub fn recommendedMaxWorkingSetSize(self: *const MetalDevice) u64
    Summary: Return the recommended working-set cap reported by Metal.
  - MetalDevice.maxThreadgroupMemoryLength [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#metal-device-max-threadgroup-memory-length
    Signature: pub fn maxThreadgroupMemoryLength(self: *const MetalDevice) u64
    Summary: Return the per-threadgroup shared-memory limit reported by Metal.
  - MetalDevice.hasUnifiedMemory [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#metal-device-has-unified-memory
    Signature: pub fn hasUnifiedMemory(self: *const MetalDevice) bool
    Summary: Return whether the active device exposes unified CPU/GPU memory.
  - MetalDevice.supportsRaytracing [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#metal-device-supports-raytracing
    Signature: pub fn supportsRaytracing(self: *const MetalDevice) bool
    Summary: Return whether the active device reports public raytracing support.

### Module: Kernel Timing
URL: https://zolotukhin.ai/zinc/docs/zig-api/kernel-timing/
Source: src/metal/kernel_timing.zig
Code lines: 167
Summary: Per-kernel Metal dispatch timing probe — default-off, env-flag-gated.
Overview: When `ZINC_METAL_KERNEL_TIMING=1` is set at engine init, every compute dispatch is wrapped in commit+wait+restart inside `MetalCommand.dispatch*` so we can measure CPU-side end-to-end ns per dispatch. The probe is intentionally destructive to throughput (each dispatch becomes a GPU sync point) and is intended ONLY for `--profile` runs where evidence about which kernels dominate dispatch cost matters more than absolute tok/s.
Overview: Aggregation is keyed by pipeline pointer plus label. Dispatch sites can set a one-shot label for shape-specific probes; otherwise the label comes from `MetalPipeline.name` set at shader load time in forward_metal.zig.

- enabled [variable]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kernel-timing/#enabled
  Signature: pub var enabled: bool = false
  Summary: Toggled true at engine init when `ZINC_METAL_KERNEL_TIMING=1`.

- Entry [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kernel-timing/#entry
  Signature: pub const Entry = struct
  Summary: Snapshot view of one pipeline's aggregated dispatch cost.

- enable [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kernel-timing/#enable
  Signature: pub fn enable() void
  Summary: Enable the probe for the rest of the process.
  Description: Idempotent.

- reset [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kernel-timing/#reset
  Signature: pub fn reset() void
  Summary: Clear accumulated stats.
  Description: Typically called at the start of a profile request.

- record [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kernel-timing/#record
  Signature: pub fn record(pipe_handle: ?*const anyopaque, name: ?[]const u8, elapsed_ns: u64) void
  Summary: Record one dispatch worth of elapsed ns against a pipeline.
  Description: Cheap when `enabled` is false (skips early at the call site).

- topByTotalNs [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kernel-timing/#top-by-total-ns
  Signature: pub fn topByTotalNs(buf: []Entry) []Entry
  Summary: Fill `buf` with up to `buf.len` entries ranked by descending total_ns.
  Description: Returns the populated prefix slice.

- topByAvgNs [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kernel-timing/#top-by-avg-ns
  Signature: pub fn topByAvgNs(buf: []Entry) []Entry
  Summary: Fill `buf` with up to `buf.len` entries ranked by descending avg_ns.
  Description: Returns the populated prefix slice.

### Module: Pipeline
URL: https://zolotukhin.ai/zinc/docs/zig-api/pipeline/
Source: src/metal/pipeline.zig
Code lines: 106
Summary: Metal compute pipeline wrapper — MSL source or precompiled metallib.
Overview: It compiles or loads Metal kernels, exposes the threadgroup capabilities that dispatch code needs for tuning, and keeps pipeline lifecycle handling out of the higher-level runtime and benchmark paths.

- MetalPipeline [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/pipeline/#metal-pipeline
  Signature: pub const MetalPipeline = struct
  Summary: A compiled Metal compute pipeline state ready for dispatch.

- createPipeline [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/pipeline/#create-pipeline
  Signature: pub fn createPipeline(ctx: ?*shim.MetalCtx, msl_source: [*:0]const u8, fn_name: [*:0]const u8) !MetalPipeline
  Summary: Compile an MSL source string into a compute pipeline for the given function name.

- createPipelineFromLib [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/pipeline/#create-pipeline-from-lib
  Signature: pub fn createPipelineFromLib(ctx: ?*shim.MetalCtx, lib_data: [*]const u8, lib_size: usize, fn_name: [*:0]const u8) !MetalPipeline
  Summary: Create a compute pipeline from a precompiled metallib binary blob.

- freePipeline [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/pipeline/#free-pipeline
  Signature: pub fn freePipeline(pipe: *MetalPipeline) void
  Summary: Release the pipeline handle.
  Description: Safe to call with a null handle.

## Managed Models

Catalog metadata, cache management, model downloads, and active-selection helpers used by the CLI and server.
URL: https://zolotukhin.ai/zinc/docs/zig-api#managed-models

### Module: Catalog
URL: https://zolotukhin.ai/zinc/docs/zig-api/catalog/
Source: src/model/catalog.zig
Code lines: 429
Summary: Curated catalog of ZINC-supported managed GGUF models.
Overview: The catalog is intentionally small and only includes models that ZINC has explicitly validated for the listed GPU profiles.

- CatalogStatus [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/catalog/#catalog-status
  Signature: pub const CatalogStatus = enum
  Summary: Lifecycle status of a catalog entry, controlling visibility and UI treatment.

- CatalogEntry [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/catalog/#catalog-entry
  Signature: pub const CatalogEntry = struct
  Summary: A single managed-model entry describing its identity, download location, hardware requirements, and tested GPU profiles.

- FitState [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/catalog/#fit-state
  Signature: pub const FitState = enum
  Summary: VRAM-fit assessment for a catalog entry against a specific GPU budget.

- apple_silicon_profile [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/catalog/#apple-silicon-profile
  Signature: pub const apple_silicon_profile = "apple-silicon"
  Summary: Shared GPU profile string used for all Apple Silicon (Metal) devices.

- entries [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/catalog/#entries
  Signature: pub const entries = [_]CatalogEntry{
  Summary: The complete list of ZINC-validated managed models available for download.

- find [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/catalog/#find
  Signature: pub fn find(id: []const u8) ?*const CatalogEntry
  Summary: Look up a catalog entry by its short identifier, returning null if not found.

- findForLoadedModel [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/catalog/#find-for-loaded-model
  Signature: pub fn findForLoadedModel(managed_id: ?[]const u8, model_path: []const u8, display_name: []const u8) ?*const CatalogEntry
  Summary: Match a loaded model back to a catalog entry, even when it was opened from a raw path instead of a managed-model id.
  Description: Resolution order: managed id → parent directory name (for managed-cache `model.gguf` paths) → file-name exact match → file-name compact-case-insensitive match → display-name fuzzy match.
  Param managed_id: Optional catalog id previously recorded for this model; tried first.
  Param model_path: Absolute filesystem path to the GGUF file being loaded.
  Param display_name: Human-readable name used as a last-resort fuzzy key.
  Returns: Pointer into `entries`, or null when no catalog entry matches.

- profileForGpu [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/catalog/#profile-for-gpu
  Signature: pub fn profileForGpu(config: gpu_detect.GpuConfig) []const u8
  Summary: Map a detected Vulkan GPU configuration to its catalog profile string.
  Description: RDNA4 is split by VRAM tier (≥28 GiB → "amd-rdna4-32gb", ≥14 GiB → "amd-rdna4-16gb", otherwise "amd-rdna4-small"); RDNA3 is split by VRAM tier (≥14 GiB → "amd-rdna3-16gb", otherwise "amd-rdna3-small"); all other vendors map to a single string each.
  Param config: GPU vendor/VRAM description produced by `gpu_detect`.
  Returns: Catalog profile key that can be matched against `CatalogEntry.tested_profiles`.

- profileForMetal [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/catalog/#profile-for-metal
  Signature: pub fn profileForMetal() []const u8
  Summary: Return the catalog profile string for Apple Silicon Metal devices.

- nvidia_cuda_profile [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/catalog/#nvidia-cuda-profile
  Signature: pub const nvidia_cuda_profile = "nvidia-cuda"
  Summary: Shared GPU profile string used for all NVIDIA (CUDA) devices.

- profileForCuda [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/catalog/#profile-for-cuda
  Signature: pub fn profileForCuda() []const u8
  Summary: Return the catalog profile string for NVIDIA CUDA devices.
  Description: The CUDA backend does not split by VRAM tier the way Vulkan/RDNA4 does — fit is decided by the live `freeMemory()` budget — so a single profile string is sufficient.

- supportsProfile [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/catalog/#supports-profile
  Signature: pub fn supportsProfile(entry: CatalogEntry, profile: []const u8) bool
  Summary: Return whether the entry has been tested on the given GPU profile.
  Param entry: Catalog entry to check.
  Param profile: Profile string such as `"amd-rdna4-32gb"` or `apple_silicon_profile`.
  Returns: true if `profile` appears in `entry.tested_profiles`.

- fitsGpu [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/catalog/#fits-gpu
  Signature: pub fn fitsGpu(entry: CatalogEntry, vram_budget_bytes: u64) bool
  Summary: Return whether the model's VRAM requirement fits within the given budget without enabling MoE offload.
  Description: Strict — does not consider the offload escape hatch. Use `fitState` for the offload-aware tri-state assessment.

- requiredVramWithOffload [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/catalog/#required-vram-with-offload
  Signature: pub fn requiredVramWithOffload(entry: CatalogEntry) u64
  Summary: VRAM required when MoE expert tensors are offloaded to host RAM.
  Description: Equal to `required_vram_bytes` for dense models (no offloadable tensors).

- fitState [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/catalog/#fit-state
  Signature: pub fn fitState(entry: CatalogEntry, vram_budget_bytes: u64) FitState
  Summary: Tri-state fit assessment that distinguishes "fits as-is" from "fits only with `ZINC_OFFLOAD_MOE_EXPERTS=1`".
  Description: Use this to surface the offload escape hatch to users when a model would otherwise look unsupported.

- requiresOffloadToFit [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/catalog/#requires-offload-to-fit
  Signature: pub fn requiresOffloadToFit(entry: CatalogEntry, vram_budget_bytes: u64) bool
  Summary: Return true when the model needs `ZINC_OFFLOAD_MOE_EXPERTS=1` to fit (does not fit by itself but does fit with offload enabled).

- supportedOnCurrentGpu [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/catalog/#supported-on-current-gpu
  Signature: pub fn supportedOnCurrentGpu(entry: CatalogEntry, profile: []const u8, vram_budget_bytes: u64) bool
  Summary: Return whether the model is both tested on the given profile and fits in VRAM without MoE offload.
  Description: Equivalent to `supportsProfile and fitsGpu`.
  Param entry: Catalog entry to evaluate.
  Param profile: Detected GPU profile string (e.g. from `profileForGpu`).
  Param vram_budget_bytes: Available VRAM budget in bytes.
  Returns: true only when both conditions hold; does not consider offload.

- ggufArchForFamily [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/catalog/#gguf-arch-for-family
  Signature: pub fn ggufArchForFamily(family: []const u8) ?[]const u8
  Summary: Map a catalog family string to the GGUF architecture string that models in that family use.
  Description: Returns null for unrecognized families — the caller should treat that as an error (a catalog entry with no known architecture mapping). Note that `"qwen3.5"` and `"qwen3.6"` both map to `"qwen35"` because the GGUF file declares the SSM+attention hybrid architecture under that name.
  Param family: Value of `CatalogEntry.family` (e.g. `"gemma4"`, `"qwen3.6"`).
  Returns: GGUF architecture identifier, or null if the family is not recognized.

### Module: Hf
URL: https://zolotukhin.ai/zinc/docs/zig-api/hf/
Source: src/model/hf.zig
Code lines: 405
Summary: Resolve and download Hugging Face GGUF models for the `-hf` CLI flag.
Overview: Turns an `owner/repo[:quant]` spec into an installed GGUF in the managed model cache, resolving the concrete file name via the Hugging Face `/v2/<repo>/manifests/<tag>` endpoint and reusing the managed download pipeline for transfer, staging, and manifest bookkeeping.

- Spec [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/hf/#spec
  Signature: pub const Spec = struct
  Summary: Parsed `-hf` argument: a Hugging Face repo plus a quantization tag.

- parseSpec [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/hf/#parse-spec
  Signature: pub fn parseSpec(text: []const u8) !Spec
  Summary: Parses an `-hf` argument of the form `owner/repo[:quant]`.
  Description: The quantization suffix is optional; when absent the tag defaults to `latest`, which the Hugging Face manifest endpoint resolves to the repo's recommended quantization. Each component (owner, repo, tag) must match the Hugging Face naming grammar; anything else fails with `error.InvalidHfSpec`.
  Param text: Raw CLI argument value.
  Returns: A `Spec` whose slices point into `text`.

- cacheId [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/hf/#cache-id
  Signature: pub fn cacheId(allocator: std.mem.Allocator, spec: Spec) ![]u8
  Summary: Derives the managed-cache model id for a Hugging Face spec.
  Description: The id is a single filesystem-safe path component so the download can live in the same `<cache_root>/models/<id>/model.gguf` layout as catalog models. Distinct specs map to distinct ids; `:latest` is cached separately from an explicit quantization even if both resolve to the same upstream file.
  Param allocator: Owns the returned id slice.
  Param spec: Parsed Hugging Face spec.
  Returns: Heap-allocated id like `hf--unsloth--qwen3.5-9b-gguf--q4_k_m`.

- ensureModel [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/hf/#ensure-model
  Signature: pub fn ensureModel(spec_text: []const u8, allocator: std.mem.Allocator, writer: anytype) ![]u8
  Summary: Ensures the model described by an `-hf` spec is installed and returns its path.
  Description: If the spec is already cached the installed path is returned without any network access. Otherwise the GGUF file name and sha256 digest are resolved via the Hugging Face manifest endpoint and the file is downloaded through the managed pull pipeline (staged `.partial` file, progress bar, manifest write), which verifies the download against the pinned digest when the manifest provides one. quantizations with no kernels (`error.UnsupportedQuantization`, detected from the tag and the resolved file name) and architectures the loader does not recognise (`error.UnsupportedArchitecture`, detected from repo metadata when available).
  Param spec_text: Raw `-hf` argument (`owner/repo[:quant]`).
  Param allocator: Used for HTTP, path construction, and the returned path.
  Param writer: Receives human-readable status lines and download progress.
  Returns: Heap-allocated absolute path to the installed GGUF; caller owns it.
  Note: Models zinc cannot run are rejected before the download starts:
  Note: Gated or private repos are not supported: they fail with `error.HfAuthRequired`.

### Module: Managed
URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/
Source: src/model/managed.zig
Code lines: 1044
Summary: Managed model cache, active-model selection, and download helpers.
Overview: These helpers back the `zinc model ...` CLI and the server-side active-model switching flow.

- RuntimePaths [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#runtime-paths
  Signature: pub const RuntimePaths = struct
  Summary: Resolved cache and config directory paths for the current platform.
  - RuntimePaths.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#runtime-paths-deinit
    Signature: pub fn deinit(self: *RuntimePaths, allocator: std.mem.Allocator) void
    Summary: Frees the owned path slices and invalidates the struct.

- ModelFit [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#model-fit
  Signature: pub const ModelFit = struct
  Summary: VRAM budget check result for a single catalog model.

- ActiveSelection [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#active-selection
  Signature: pub const ActiveSelection = struct
  Summary: The currently active managed model as persisted in the config directory.
  - ActiveSelection.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#active-selection-deinit
    Signature: pub fn deinit(self: *ActiveSelection, allocator: std.mem.Allocator) void
    Summary: Frees the owned model_id slice and invalidates the struct.

- CachedGpuProfile [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#cached-gpu-profile
  Signature: pub const CachedGpuProfile = struct
  Summary: Cached GPU capability profile used to avoid re-probing the device on every run.
  - CachedGpuProfile.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#cached-gpu-profile-deinit
    Signature: pub fn deinit(self: *CachedGpuProfile, allocator: std.mem.Allocator) void
    Summary: Frees the owned string slices and invalidates the struct.

- InstalledManifest [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#installed-manifest
  Signature: pub const InstalledManifest = struct
  Summary: On-disk manifest written alongside an installed GGUF model file.
  Description: `sha256` is optional: hand-rolled manifests for symlinked local files (e.g. `download_url:"local"`) frequently omit it because the user can't or won't precompute the digest of an existing GGUF. Treat it as a hint, not a required field — the catalog's `sha256` is the source of truth when a checksum needs to be enforced.
  - InstalledManifest.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#installed-manifest-deinit
    Signature: pub fn deinit(self: *InstalledManifest, allocator: std.mem.Allocator) void
    Summary: Frees the owned sha256 slice (if any) and invalidates the struct.

- RemoveInstalledModelResult [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#remove-installed-model-result
  Signature: pub const RemoveInstalledModelResult = struct
  Summary: Outcome of a model removal: which artifacts were actually deleted.

- DownloadObserver [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#download-observer
  Signature: pub const DownloadObserver = struct
  Summary: Callback hooks for observing model download lifecycle events.

- runtimePaths [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#runtime-paths
  Signature: pub fn runtimePaths(allocator: std.mem.Allocator) !RuntimePaths
  Summary: Returns the resolved cache and config root directories for the current platform.

- resolveInstalledModelPath [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#resolve-installed-model-path
  Signature: pub fn resolveInstalledModelPath(model_id: []const u8, allocator: std.mem.Allocator) ![]u8
  Summary: Returns the absolute path to the installed GGUF file for the given model id.
  Description: `error.InvalidModelId`, so no caller can resolve a path outside the cache.
  Param model_id: Catalog model identifier (e.g. `"qwen3-2b"`).
  Param allocator: Used to build the path; caller owns the returned slice.
  Returns: Heap-allocated absolute path `<cache_root>/models/<model_id>/model.gguf`.
  Note: Ids that are not a single filesystem-safe path component fail with

- resolveManifestPath [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#resolve-manifest-path
  Signature: pub fn resolveManifestPath(model_id: []const u8, allocator: std.mem.Allocator) ![]u8
  Summary: Returns the absolute path to the manifest JSON for the given model id.
  Description: `error.InvalidModelId`, so no caller can resolve a path outside the cache.
  Param model_id: Catalog model identifier.
  Param allocator: Used to build the path; caller owns the returned slice.
  Returns: Heap-allocated absolute path `<cache_root>/models/<model_id>/manifest.json`.
  Note: Ids that are not a single filesystem-safe path component fail with

- resolveActiveConfigPath [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#resolve-active-config-path
  Signature: pub fn resolveActiveConfigPath(allocator: std.mem.Allocator) ![]u8
  Summary: Returns the absolute path to the active-model config file.

- resolveGpuProfileCachePath [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#resolve-gpu-profile-cache-path
  Signature: pub fn resolveGpuProfileCachePath(device_index: u32, allocator: std.mem.Allocator) ![]u8
  Summary: Returns the absolute path to the cached GPU profile JSON for the given device index.
  Param device_index: Zero-based index of the GPU device; encoded in the filename.
  Param allocator: Used to build the path; caller owns the returned slice.
  Returns: Heap-allocated absolute path `<config_root>/gpu-profile-device-<device_index>.json`.

- isInstalled [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#is-installed
  Signature: pub fn isInstalled(model_id: []const u8, allocator: std.mem.Allocator) bool
  Summary: Returns true if the model GGUF file exists in the local cache.

- readActiveSelection [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#read-active-selection
  Signature: pub fn readActiveSelection(allocator: std.mem.Allocator) !?ActiveSelection
  Summary: Reads the persisted active-model selection, or returns null if none is set.

- writeActiveSelection [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#write-active-selection
  Signature: pub fn writeActiveSelection(model_id: []const u8, allocator: std.mem.Allocator) !void
  Summary: Persists the given model id as the active selection with the current timestamp.

- clearActiveSelection [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#clear-active-selection
  Signature: pub fn clearActiveSelection(allocator: std.mem.Allocator) !bool
  Summary: Removes the active-model config file.
  Description: Returns true if a file was deleted.

- clearActiveSelectionIfMatches [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#clear-active-selection-if-matches
  Signature: pub fn clearActiveSelectionIfMatches(model_id: []const u8, allocator: std.mem.Allocator) !bool
  Summary: Clears the active selection only if it currently points to the given model id.

- readCachedGpuProfile [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#read-cached-gpu-profile
  Signature: pub fn readCachedGpuProfile(device_index: u32, allocator: std.mem.Allocator) !?CachedGpuProfile
  Summary: Reads the cached GPU profile for the given device, or returns null if not cached.

- writeCachedGpuProfile [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#write-cached-gpu-profile
  Signature: pub fn writeCachedGpuProfile( device_index: u32, profile: []const u8, device_name: []const u8, vram_budget_bytes: u64, allocator: std.mem.Allocator, ) !void
  Summary: Persists a GPU capability profile to disk for the given device index.
  Description: Overwrites any existing cache file for that device.
  Param device_index: Zero-based GPU index; used to derive the cache file name.
  Param profile: Opaque profile string (e.g. `"rdna4"`) returned by the diagnostics layer.
  Param device_name: Human-readable device name stored for informational display.
  Param vram_budget_bytes: Effective VRAM budget in bytes for this device.
  Param allocator: Used only for path construction; nothing is retained after the call.

- describeFit [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#describe-fit
  Signature: pub fn describeFit(entry: catalog.CatalogEntry, vram_budget_bytes: u64, allocator: std.mem.Allocator) !ModelFit
  Summary: Returns a VRAM fit assessment for a catalog model against the given budget.
  Description: If the model is installed, the on-disk manifest is consulted first (most accurate); if the manifest lacks VRAM fields, the installed GGUF is inspected directly and the manifest is updated. For models that are not yet installed, catalog static estimates are used and `ModelFit.exact` is false.
  Param entry: Catalog entry describing the model to assess.
  Param vram_budget_bytes: Available VRAM in bytes on the target device.
  Param allocator: Used for path resolution and manifest I/O; nothing is retained.
  Returns: `ModelFit` with exact=true when data came from the installed model (manifest or file inspection), false for catalog estimates.

- verifyActiveSelectionFits [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#verify-active-selection-fits
  Signature: pub fn verifyActiveSelectionFits(model_id: []const u8, vram_budget_bytes: u64, allocator: std.mem.Allocator) !ModelFit
  Summary: Verifies that the named model is installed and fits in the given VRAM budget.
  Description: Returns `error.UnknownManagedModel` if `model_id` is not in the catalog, or `error.ModelNotInstalled` if the GGUF file is absent from the local cache.
  Param model_id: Catalog model identifier to check.
  Param vram_budget_bytes: Available VRAM in bytes on the target device.
  Param allocator: Forwarded to `describeFit` for path and manifest I/O.
  Returns: `ModelFit` describing the exact VRAM requirement and fit state.

- removeInstalledModel [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#remove-installed-model
  Signature: pub fn removeInstalledModel(model_id: []const u8, allocator: std.mem.Allocator) !RemoveInstalledModelResult
  Summary: Deletes an installed model's GGUF, manifest, and (if empty) its directory.

- pullModel [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#pull-model
  Signature: pub fn pullModel(entry: catalog.CatalogEntry, allocator: std.mem.Allocator, writer: anytype) !void
  Summary: Downloads and installs a model from the catalog, verifying its sha256 checksum.

- pullModelWithObserver [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#pull-model-with-observer
  Signature: pub fn pullModelWithObserver( entry: catalog.CatalogEntry, allocator: std.mem.Allocator, writer: anytype, observer: ?*const DownloadObserver, ) !void
  Summary: Downloads and installs a model, reporting progress via an optional observer.
  Description: If the model is already installed and its sha256 matches the catalog, the function returns immediately without re-downloading. A `.partial` staging file is used so an interrupted download does not corrupt the cache.
  Param entry: Catalog entry that supplies the download URL and expected sha256.
  Param allocator: Used for HTTP client, path construction, and temporary buffers.
  Param writer: Receives human-readable status lines and the download progress bar.
  Param observer: Optional lifecycle callbacks for programmatic progress tracking; pass null to skip.

- bytesToGiB [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/managed/#bytes-to-gi-b
  Signature: pub fn bytesToGiB(bytes: u64) f64
  Summary: Converts a byte count to gibibytes (GiB) as a floating-point value.

### Module: Model Manager
URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager/
Source: src/server/model_manager.zig
Code lines: 686
Summary: Managed active-model runtime state for the HTTP server and CLI startup.
Overview: ZINC still loads one model into memory at a time. This manager keeps the current engine/tokenizer/model bundle together and handles serialized swaps.

- LoadSpec [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager/#load-spec
  Signature: pub const LoadSpec = struct
  Summary: Describes which model to load: a filesystem path, an optional managed-catalog ID, and an optional context-length override.

- ModelSummary [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager/#model-summary
  Signature: pub const ModelSummary = struct
  Summary: Flat representation of a catalog model for JSON serialization to API clients.

- ModelCatalogView [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager/#model-catalog-view
  Signature: pub const ModelCatalogView = struct
  Summary: Snapshot of the full model catalog annotated with the current GPU profile.
  - ModelCatalogView.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager/#model-catalog-view-deinit
    Signature: pub fn deinit(self: *ModelCatalogView, allocator: std.mem.Allocator) void
    Summary: Frees the owned summary slice.

- LoadedResources [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager/#loaded-resources
  Signature: pub const LoadedResources = struct
  Summary: Bundle of model, tokenizer, and inference engine that represents a fully loaded model.

- ModelManager [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager/#model-manager
  Signature: pub const ModelManager = struct
  Summary: Thread-safe owner of the currently active model, providing load, swap, and catalog queries.
  - ModelManager.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager/#model-manager-init
    Signature: pub fn init( spec: LoadSpec, instance: *const Instance, gpu_config_value: gpu_detect.GpuConfig, shader_dir: []const u8, allocator: std.mem.Allocator, ) !ModelManager
    Summary: Creates a manager and immediately loads the model described by `spec`.
    Description: Acquires the per-device GPU process lock before loading. or an error if loading fails.
    Param spec: Path, optional catalog ID, and optional context-length override for the model to load.
    Param instance: Vulkan instance that owns the selected GPU device.
    Param gpu_config_value: Detected GPU capabilities used for shader selection and catalog filtering.
    Param shader_dir: Filesystem path to the directory containing compiled SPIR-V shaders.
    Param allocator: Used for all heap allocations owned by this manager.
    Returns: An initialised `ModelManager` with `current` pointing to the loaded resources,
  - ModelManager.initEmpty [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager/#model-manager-init-empty
    Signature: pub fn initEmpty( instance: *const Instance, gpu_config_value: gpu_detect.GpuConfig, shader_dir: []const u8, requested_context_length: ?u32, allocator: std.mem.Allocator, ) ModelManager
    Summary: Creates a manager with no model loaded; the server starts idle and the GPU lock is not held.
    Param instance: Vulkan instance that owns the selected GPU device.
    Param gpu_config_value: Detected GPU capabilities used for catalog filtering.
    Param shader_dir: Filesystem path to the directory containing compiled SPIR-V shaders.
    Param requested_context_length: Optional token-count override applied when a model is later activated.
    Param allocator: Used for all heap allocations owned by this manager.
  - ModelManager.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager/#model-manager-deinit
    Signature: pub fn deinit(self: *ModelManager) void
    Summary: Tears down the loaded model (if any) and releases all owned resources.
  - ModelManager.currentResources [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager/#model-manager-current-resources
    Signature: pub fn currentResources(self: *ModelManager) ?*LoadedResources
    Summary: Returns a pointer to the active model resources, or null if none is loaded.
  - ModelManager.activeDisplayName [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager/#model-manager-active-display-name
    Signature: pub fn activeDisplayName(self: *ModelManager) []const u8
    Summary: Returns the human-readable name of the active model, or `"none"`.
  - ModelManager.catalogProfile [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager/#model-manager-catalog-profile
    Signature: pub fn catalogProfile(self: *const ModelManager) []const u8
    Summary: Returns the catalog profile string for the detected GPU (e.g.
    Description: `"amd-rdna4-32gb"`).
  - ModelManager.currentMemoryUsage [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager/#model-manager-current-memory-usage
    Signature: pub fn currentMemoryUsage(self: *ModelManager) MemoryUsage
    Summary: Snapshots the VRAM usage of the active model, or returns zeroes with the full VRAM budget in `device_local_budget_bytes` if idle.
  - ModelManager.collectCatalogView [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager/#model-manager-collect-catalog-view
    Signature: pub fn collectCatalogView(self: *ModelManager, allocator: std.mem.Allocator, include_all: bool) !ModelCatalogView
    Summary: Builds a catalog snapshot with install/active/fit status for every entry.
    Description: When `include_all` is false, entries unsupported on the current GPU are excluded.
  - ModelManager.supportsManagedEntry [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager/#model-manager-supports-managed-entry
    Signature: pub fn supportsManagedEntry(self: *ModelManager, entry: catalog_mod.CatalogEntry, allocator: std.mem.Allocator) bool
    Summary: Reports whether a catalog entry is both GPU-architecture-compatible and fits within the current VRAM budget.
    Param entry: The catalog entry to evaluate.
    Param allocator: Used for temporary allocations during fit computation; no long-lived allocation is made.
    Returns: `true` when the entry matches the detected GPU profile and `describeFit` reports it fits.
  - ModelManager.activateManagedModel [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager/#model-manager-activate-managed-model
    Signature: pub fn activateManagedModel(self: *ModelManager, model_id: []const u8, persist_active: bool, force: bool) !void
    Summary: Loads and activates a managed catalog model, replacing any currently loaded model.
    Description: If the requested model is already active the function returns immediately (optionally persisting the selection). The GPU process lock is acquired if not already held. survives process restarts. detected GPU is rejected with `error.ModelUnsupportedOnThisGpu`; when true, activation proceeds on the untested profile with only a logged warning. `error.ModelUnsupportedOnThisGpu` if the entry is not validated on this GPU and `force` is false, `error.ModelNotInstalled` if the weights file is absent, or `error.ModelDoesNotFit` if the model exceeds the VRAM budget.
    Param model_id: Catalog entry ID to activate; must be installed on disk.
    Param persist_active: When true, writes the selection to the active-model file so it
    Param force: When false, an entry whose tested profiles do not include the
    Returns: `error.UnknownManagedModel` if the ID is not in the catalog,
    Note: Caller must hold the shared generation lock before calling this function.
  - ModelManager.removeManagedModel [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager/#model-manager-remove-managed-model
    Signature: pub fn removeManagedModel(self: *ModelManager, model_id: []const u8, force: bool) !RemoveResult
    Summary: Uninstalls a managed model from disk and, if it is currently loaded, optionally evicts it from the GPU.
    Description: active. When `true`, the model is unloaded from the GPU before deletion. active-selection file was updated.
    Param model_id: Catalog entry ID of the model to remove.
    Param force: When `false`, returns `error.ModelLoadedInGpu` if the model is currently
    Returns: A `RemoveResult` describing whether the GPU was cleared and whether the
    Note: Caller must hold the shared generation lock before calling this function.

## Scheduler

Continuous batching scheduler, paged KV cache management, and request lifecycle tracking for concurrent inference serving.
URL: https://zolotukhin.ai/zinc/docs/zig-api#scheduler

### Module: KV Cache
URL: https://zolotukhin.ai/zinc/docs/zig-api/kv-cache/
Source: src/scheduler/kv_cache.zig
Code lines: 187
Summary: Paged KV cache manager for concurrent request serving.
Overview: Manages a pool of fixed-size pages that are allocated per-request and freed on completion or cancellation. Each page maps to a contiguous region of the GPU KV cache buffer, giving each request non-overlapping token storage.

- KvPage [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kv-cache/#kv-page
  Signature: pub const KvPage = struct
  Summary: A single page in the KV cache pool.
  Description: Each page maps to a contiguous region of the GPU KV buffer.

- KvPagePool [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/kv-cache/#kv-page-pool
  Signature: pub const KvPagePool = struct
  Summary: Pool-based allocator for KV cache pages.
  Description: Tracks which pages are free and which are owned by active requests.
  - KvPagePool.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/kv-cache/#kv-page-pool-init
    Signature: pub fn init(allocator: std.mem.Allocator, total_pages: u32, page_size: u32) !KvPagePool
    Summary: Initialize a page pool with the given number of pages and tokens per page.
    Param allocator: Allocator for the page array and free list.
    Param total_pages: Number of pages to create.
    Param page_size: Number of tokens each page can hold.
    Returns: A KvPagePool with all pages initially free.
  - KvPagePool.allocPages [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/kv-cache/#kv-page-pool-alloc-pages
    Signature: pub fn allocPages(self: *KvPagePool, request_id: u64, count: u32) ![]u32
    Summary: Allocate `count` pages for a request and stamp them with `request_id`.
    Param request_id: Owner request ID recorded on each allocated page.
    Param count: Number of pages to allocate.
    Returns: Slice of allocated page IDs; caller must free it with the pool's allocator.
    Note: Returns error.KvCacheExhausted if fewer than `count` free pages remain.
  - KvPagePool.freePages [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/kv-cache/#kv-page-pool-free-pages
    Signature: pub fn freePages(self: *KvPagePool, request_id: u64) void
    Summary: Free all pages owned by a request, returning them to the free list.
    Description: Performs a linear scan over all pages; O(total_pages).
    Param request_id: Request whose pages should be freed.
  - KvPagePool.positionBase [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/kv-cache/#kv-page-pool-position-base
    Signature: pub fn positionBase(self: *const KvPagePool, page_ids: []const u32) u32
    Summary: Return the token position base for a request's first allocated page.
    Description: Computed as `page_ids[0] * page_size`, which guarantees non-overlapping token storage across requests since each page_id maps to a disjoint range.
    Param page_ids: Allocated page IDs for the request (must be non-empty to get a meaningful result).
    Returns: Token index of the first token slot owned by this request, or 0 if `page_ids` is empty.
  - KvPagePool.maxContext [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/kv-cache/#kv-page-pool-max-context
    Signature: pub fn maxContext(self: *const KvPagePool, page_count: u32) u32
    Summary: Maximum context length (in tokens) that fits in `page_count` allocated pages.
    Param page_count: Number of pages allocated to the request.
    Returns: `page_count * page_size` — the token capacity for those pages.
  - KvPagePool.freeCount [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/kv-cache/#kv-page-pool-free-count
    Signature: pub fn freeCount(self: *const KvPagePool) u32
    Summary: Number of free pages currently available for allocation.
    Returns: Count of unallocated pages remaining in the pool.
  - KvPagePool.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/kv-cache/#kv-page-pool-deinit
    Signature: pub fn deinit(self: *KvPagePool) void
    Summary: Release the page array and free list back to the allocator.

### Module: Request
URL: https://zolotukhin.ai/zinc/docs/zig-api/request/
Source: src/scheduler/request.zig
Code lines: 191
Summary: Request lifecycle management for concurrent inference serving.
Overview: Each incoming API request maps to a Request that tracks its state through prefill, decode, and completion phases.

- RequestState [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/request/#request-state
  Signature: pub const RequestState = enum
  Summary: Request processing state machine.
  Description: Valid transitions: pending → prefilling → decoding → completed, with cancelled reachable from any active state and failed reachable from prefilling or decoding.

- GenerationParams [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/request/#generation-params
  Signature: pub const GenerationParams = struct
  Summary: Generation parameters from the API request.

- Request [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/request/#request
  Signature: pub const Request = struct
  Summary: A single inference request with its lifecycle state.
  - Request.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/request/#request-init
    Signature: pub fn init(allocator: std.mem.Allocator, id: u64, prompt_tokens: []const u32, params: GenerationParams) Request
    Summary: Create a new request in the pending state with the given prompt and parameters.
    Param allocator: Allocator for the generated token buffer.
    Param id: Unique request identifier.
    Param prompt_tokens: Tokenized prompt (owned by the caller).
    Param params: Generation parameters (max_tokens, temperature, etc.).
    Returns: A Request ready to be submitted to the scheduler.
  - Request.transition [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/request/#request-transition
    Signature: pub fn transition(self: *Request, new_state: RequestState) !void
    Summary: Advance the request through the state machine.
    Param self: Request to transition.
    Param new_state: Target state (must be a valid successor of the current state).
    Returns: error.InvalidTransition if the transition is not allowed by the state machine.
  - Request.appendToken [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/request/#request-append-token
    Signature: pub fn appendToken(self: *Request, token: u32) !void
    Summary: Append a generated token and record the first-token timestamp if unset.
    Param self: Request to append to.
    Param token: Generated token ID to add.
  - Request.shouldStop [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/request/#request-should-stop
    Signature: pub fn shouldStop(self: *const Request, eos_token_id: u32) bool
    Summary: Check if generation should stop (max_tokens reached or EOS token emitted).
    Param self: Request to check.
    Param eos_token_id: End-of-sequence token ID.
    Returns: True if generation should stop.
  - Request.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/request/#request-deinit
    Signature: pub fn deinit(self: *Request) void
    Summary: Release the generated token buffer owned by this request.
    Param self: Request to tear down.

### Module: Scheduler
URL: https://zolotukhin.ai/zinc/docs/zig-api/scheduler/
Source: src/scheduler/scheduler.zig
Code lines: 380
Summary: Continuous-batching scheduler groundwork for concurrent inference requests.
Overview: Today this module owns request slot accounting and state collection only. The HTTP serving hot path still serializes generation behind ServerState.generation_mutex; the batched prefill/decode dispatch loop is not wired yet.

- Scheduler [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/scheduler/#scheduler
  Signature: pub const Scheduler = struct
  Summary: Fixed-capacity pool of request slots used to track concurrent inference requests.
  Description: Each slot holds at most one active `Request`; slots are reused once released.
  - Scheduler.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/scheduler/#scheduler-init
    Signature: pub fn init(allocator: std.mem.Allocator, max_parallel: u32) !Scheduler
    Summary: Initialize the scheduler with a fixed number of concurrent request slots.
    Param allocator: Allocator for the slot array.
    Param max_parallel: Maximum number of concurrent requests.
    Returns: A Scheduler with all slots initially empty.
  - Scheduler.enqueue [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/scheduler/#scheduler-enqueue
    Signature: pub fn enqueue(self: *Scheduler, prompt_tokens: []const u32, params: GenerationParams) !u64
    Summary: Enqueue a new request without assigning a slot (continuous-batching path).
    Description: The request sits in `pending` (state `.pending`) until `admitNext` moves it into a free slot. Unlike `submit`, this never fails on a full slot array — arrivals queue and are admitted as slots free, which is what lets a running batch admit/evict sequences between decode steps.
    Returns: The new request's unique id.
  - Scheduler.admitNext [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/scheduler/#scheduler-admit-next
    Signature: pub fn admitNext(self: *Scheduler) !?u32
    Summary: Admit the oldest pending request into the first free slot, if any.
    Description: Moves it out of the `pending` queue, assigns `slot_id`, and transitions it to `.prefilling`. The caller then runs prefill for every slot reported by `pendingPrefill` and transitions those to `.decoding`.
    Returns: The assigned slot index, or null if no pending request or no free slot.
  - Scheduler.hasFreeSlot [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/scheduler/#scheduler-has-free-slot
    Signature: pub fn hasFreeSlot(self: *const Scheduler) bool
    Summary: True if at least one slot is free.
  - Scheduler.isIdle [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/scheduler/#scheduler-is-idle
    Signature: pub fn isIdle(self: *const Scheduler) bool
    Summary: True if there is no outstanding work: every slot empty and no waiters.
  - Scheduler.submit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/scheduler/#scheduler-submit
    Signature: pub fn submit(self: *Scheduler, prompt_tokens: []const u32, params: GenerationParams) !u32
    Summary: Submit a new request and assign it to the first free slot.
    Param self: Scheduler to submit to.
    Param prompt_tokens: Tokenized prompt for the request.
    Param params: Generation parameters (max_tokens, temperature, etc.).
    Returns: The slot index that was assigned; pass this value to `release` when the request completes.
    Note: Returns `error.AllSlotsBusy` if every slot is occupied.
  - Scheduler.isFull [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/scheduler/#scheduler-is-full
    Signature: pub fn isFull(self: *const Scheduler) bool
    Summary: Check if all slots are occupied.
    Param self: Scheduler to query.
    Returns: True if every slot holds an active request.
  - Scheduler.activeCount [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/scheduler/#scheduler-active-count
    Signature: pub fn activeCount(self: *const Scheduler) u32
    Summary: Get the number of active (non-null) requests.
    Param self: Scheduler to query.
    Returns: Count of occupied slots.
  - Scheduler.transition [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/scheduler/#scheduler-transition
    Signature: pub fn transition(self: *Scheduler, slot_id: u32, new_state: RequestState) !void
    Summary: Transition a live slot through the request state machine.
    Param self: Scheduler to query.
    Param slot_id: Slot index to update.
    Param new_state: Target request state.
    Returns: error.InvalidSlot if the slot is out of range or empty.
  - Scheduler.collectByState [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/scheduler/#scheduler-collect-by-state
    Signature: pub fn collectByState(self: *const Scheduler, state: RequestState, out: []u32) []u32
    Summary: Collect slot IDs whose request currently has `state`.
    Param self: Scheduler to query.
    Param state: Request state to match.
    Param out: Caller-owned scratch buffer for slot IDs.
    Returns: A slice of `out` containing the collected slot IDs.
  - Scheduler.pendingPrefill [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/scheduler/#scheduler-pending-prefill
    Signature: pub fn pendingPrefill(self: *Scheduler) []u32
    Summary: Slot IDs of requests in the `.prefilling` state (admitted, prompt not yet processed).
    Description: The driver runs prefill for each, then transitions it to `.decoding`. activeDecoding call.
    Returns: A slice into `self.scratch`, valid until the next pendingPrefill /
  - Scheduler.activeDecoding [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/scheduler/#scheduler-active-decoding
    Signature: pub fn activeDecoding(self: *Scheduler) []u32
    Summary: Slot IDs of requests in the `.decoding` state (the running decode batch).
    Description: The driver gathers (token, position, slot) per id and issues ONE batched decode step over them. activeDecoding call.
    Returns: A slice into `self.scratch`, valid until the next pendingPrefill /
  - Scheduler.release [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/scheduler/#scheduler-release
    Signature: pub fn release(self: *Scheduler, slot_id: u32) void
    Summary: Release a completed or cancelled request's slot, freeing its resources.
    Param self: Scheduler to release from.
    Param slot_id: Slot index to free (the value returned by `submit`).
    Note: Silently does nothing if `slot_id` is out of range or the slot is already empty.
  - Scheduler.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/scheduler/#scheduler-deinit
    Signature: pub fn deinit(self: *Scheduler) void
    Summary: Tear down all active and pending requests and free owned buffers.
    Param self: Scheduler to destroy.

## API Server

OpenAI-compatible HTTP server, route dispatch, SSE streaming, and session management for serving inference over the network.
URL: https://zolotukhin.ai/zinc/docs/zig-api#api-server

### Module: Http
URL: https://zolotukhin.ai/zinc/docs/zig-api/http/
Source: src/server/http.zig
Code lines: 334
Summary: Minimal HTTP/1.1 server for the OpenAI-compatible inference API.
Overview: Provides connection-level request parsing, JSON and SSE response helpers, and a TCP listener that hands off accepted connections to the route dispatcher.

- Connection [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/http/#connection
  Signature: pub const Connection = struct
  Summary: Active client connection with request/response capabilities.
  Description: Wraps a TCP stream and provides helpers for reading HTTP requests and writing JSON, error, and SSE responses.
  - Connection.readRequest [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/http/#connection-read-request
    Signature: pub fn readRequest(self: *Connection) !Request
    Summary: Read and parse an HTTP/1.1 request from the connection.
    Description: Reads headers until `\r\n\r\n`, extracts method/path/Content-Length, then reads the remaining body bytes.
    Param self: Active connection to read from.
    Returns: Parsed request with method, path, and body.
  - Connection.sendJson [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/http/#connection-send-json
    Signature: pub fn sendJson(self: *Connection, status: u16, body: []const u8) !void
    Summary: Send a JSON response with the given HTTP status code.
    Param self: Active connection to write to.
    Param status: HTTP status code (200, 400, 404, etc.).
    Param body: JSON-encoded response body.
  - Connection.sendError [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/http/#connection-send-error
    Signature: pub fn sendError(self: *Connection, status: u16, err_type: []const u8, message: []const u8) !void
    Summary: Send an OpenAI-format JSON error response.
    Param self: Active connection to write to.
    Param status: HTTP status code for the error.
    Param err_type: OpenAI error type string (e.g. "invalid_request_error").
    Param message: Human-readable error message.
  - Connection.sendSseStart [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/http/#connection-send-sse-start
    Signature: pub fn sendSseStart(self: *Connection) !void
    Summary: Send SSE streaming response headers with chunked transfer encoding.
    Description: After this call, use writeSseEvent to send individual events.
    Param self: Active connection to write to.
  - Connection.writeSseEvent [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/http/#connection-write-sse-event
    Signature: pub fn writeSseEvent(self: *Connection, data: []const u8) !void
    Summary: Write a single SSE event as a chunked transfer-encoding frame.
    Param self: Active connection to write to.
    Param data: Event payload (typically JSON), sent as `data: {payload}\n\n`.
  - Connection.writeSseComment [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/http/#connection-write-sse-comment
    Signature: pub fn writeSseComment(self: *Connection, text: []const u8) !void
    Summary: Write a chunked SSE comment line (`: {text}\n\n`) to keep the connection alive.
    Description: Useful when a client or intermediate proxy would time out on a quiet stream before the next model token is ready.
    Param self: Active connection to write to.
    Param text: Comment payload sent verbatim after the `: ` prefix.
  - Connection.writeSseDone [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/http/#connection-write-sse-done
    Signature: pub fn writeSseDone(self: *Connection) !void
    Summary: Write the final SSE `[DONE]` event and send the chunked transfer terminator.
    Param self: Active connection to write to.
  - Connection.isPeerClosed [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/http/#connection-is-peer-closed
    Signature: pub fn isPeerClosed(self: *Connection) bool
    Summary: Check whether the remote connection is definitively dead, to let a streaming decode loop bail out before the next token instead of discovering the same thing on the next write.
    Description: This only reports `true` on an unambiguous signal: a TCP reset, refusal, or an already-disconnected socket. A zero-byte peek (the peer's write side reached EOF) is deliberately treated as "not closed": HTTP/1.1 clients commonly half-close the upload side right after sending the request body while still reading the response, so that signal cannot distinguish "client hung up" from "compliant client, still receiving the SSE stream". Bailing out on it would truncate valid streams for such clients — worse than the wasted decode time this function is meant to save. Only a write failure (`catch return` at each write-path call site) proves that case.
    Param self: Active connection to inspect.
    Returns: `true` only for a hard reset/refused/disconnected socket.
  - Connection.close [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/http/#connection-close
    Signature: pub fn close(self: *Connection) void
    Summary: Close the underlying TCP stream and free any heap-allocated overflow body from `readRequest`.
    Param self: Connection to close.

- Method [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/http/#method
  Signature: pub const Method = enum GET, POST, OPTIONS, UNKNOWN }
  Summary: HTTP request method parsed from the request line.
  Description: `UNKNOWN` is the fallback for any method not explicitly handled by the server.

- Server [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/http/#server
  Signature: pub const Server = struct
  Summary: HTTP server that binds and listens on a TCP port.
  Description: Accepts connections and wraps them in Connection structs for request handling.
  - Server.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/http/#server-init
    Signature: pub fn init(allocator: std.mem.Allocator, port: u16) !Server
    Summary: Bind to all interfaces on the given port and start listening.
    Param allocator: Allocator for connection resources.
    Param port: TCP port to listen on.
    Returns: A Server ready to accept connections.
  - Server.accept [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/http/#server-accept
    Signature: pub fn accept(self: *Server) !Connection
    Summary: Block until a client connects, then return a Connection for that client.
    Param self: Active server to accept on.
    Returns: A new Connection wrapping the accepted TCP stream.
  - Server.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/http/#server-deinit
    Signature: pub fn deinit(self: *Server) void
    Summary: Stop listening and release the server socket.
    Param self: Server to tear down.

### Module: Model Manager Metal
URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager-metal/
Source: src/server/model_manager_metal.zig
Code lines: 594
Summary: Metal-backed active-model runtime state for the HTTP server.
Overview: The server uses this manager to load one Metal model at a time, track the tokenizer and runtime allocations that belong to it, and project fit/status information back into the OpenAI-compatible model-management endpoints.

- LoadSpec [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager-metal/#load-spec
  Signature: pub const LoadSpec = struct
  Summary: Identifies a model to load: a GGUF file path and optional managed-catalog id.

- ModelSummary [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager-metal/#model-summary
  Signature: pub const ModelSummary = struct
  Summary: Compact view of one catalog entry for the HTTP `/v1/models` response.

- ModelCatalogView [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager-metal/#model-catalog-view
  Signature: pub const ModelCatalogView = struct
  Summary: Snapshot of the full model catalog, filtered by the current GPU profile.
  - ModelCatalogView.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager-metal/#model-catalog-view-deinit
    Signature: pub fn deinit(self: *ModelCatalogView, allocator: std.mem.Allocator) void
    Summary: Free the owned catalog summary slice.

- LoadedResources [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager-metal/#loaded-resources
  Signature: pub const LoadedResources = struct
  Summary: All GPU and host resources for a loaded model: weights, tokenizer, and inference engine.

- ModelManager [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager-metal/#model-manager
  Signature: pub const ModelManager = struct
  Summary: Thread-safe manager for the currently active model on the Metal backend.
  Description: Handles loading, hot-swapping, catalog queries, and VRAM budget enforcement.
  - ModelManager.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager-metal/#model-manager-init
    Signature: pub fn init( spec: LoadSpec, device: *const MetalDevice, allocator: std.mem.Allocator, ) !ModelManager
    Summary: Create a manager and eagerly load the model described by `spec`.
    Description: Acquires the per-device GPU process lock before touching Metal resources.
    Param spec: Path, optional managed-catalog id, and optional context-length override.
    Param device: Metal device to load weights onto.
    Param allocator: Used for all heap allocations; must outlive the returned manager.
    Returns: A fully initialised manager with a loaded model, or an error if loading fails.
  - ModelManager.initEmpty [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager-metal/#model-manager-init-empty
    Signature: pub fn initEmpty( device: *const MetalDevice, requested_context_length: ?u32, allocator: std.mem.Allocator, ) ModelManager
    Summary: Create an idle manager with no model currently loaded.
    Description: The GPU process lock is not acquired until the first model is activated. `null` lets the memory planner auto-size the context window.
    Param requested_context_length: Token limit to apply when a model is later loaded;
  - ModelManager.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager-metal/#model-manager-deinit
    Signature: pub fn deinit(self: *ModelManager) void
    Summary: Tear down the active model, if any, and release the GPU process lock.
  - ModelManager.currentResources [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager-metal/#model-manager-current-resources
    Signature: pub fn currentResources(self: *ModelManager) ?*LoadedResources
    Summary: Return the currently loaded resource bundle, or null when idle.
  - ModelManager.activeDisplayName [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager-metal/#model-manager-active-display-name
    Signature: pub fn activeDisplayName(self: *ModelManager) []const u8
    Summary: Return the active model display name, or `"none"` when no model is loaded.
  - ModelManager.catalogProfile [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager-metal/#model-manager-catalog-profile
    Signature: pub fn catalogProfile(self: *const ModelManager) []const u8
    Summary: Return the catalog profile string used for the active Metal device.
  - ModelManager.currentMemoryUsage [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager-metal/#model-manager-current-memory-usage
    Signature: pub fn currentMemoryUsage(self: *ModelManager) MemoryUsage
    Summary: Snapshot memory usage for the active model, or zeroes when idle.
  - ModelManager.collectCatalogView [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager-metal/#model-manager-collect-catalog-view
    Signature: pub fn collectCatalogView(self: *ModelManager, allocator: std.mem.Allocator, include_all: bool) !ModelCatalogView
    Summary: Build a catalog view annotated with install, fit, and active-model status.
    Description: Entries are filtered to those that are supported on the current GPU profile and fit within the VRAM budget unless `include_all` is true. The currently-active model is always included even if its static VRAM estimate exceeds the live budget. Unrecognised loaded models (raw GGUF files with no catalog entry) appear as a synthetic entry with `managed = false`.
    Param allocator: Used to allocate the returned `ModelCatalogView.data` slice; caller must call `deinit`.
    Param include_all: When true, unsupported and oversized entries are included in the result.
    Returns: An owned `ModelCatalogView`; free with `ModelCatalogView.deinit`.
  - ModelManager.supportsManagedEntry [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager-metal/#model-manager-supports-managed-entry
    Signature: pub fn supportsManagedEntry(self: *ModelManager, entry: catalog_mod.CatalogEntry, allocator: std.mem.Allocator) bool
    Summary: Return whether a managed catalog entry is supported and fits on the active device.
  - ModelManager.activateManagedModel [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager-metal/#model-manager-activate-managed-model
    Signature: pub fn activateManagedModel(self: *ModelManager, model_id: []const u8, persist_active: bool, force: bool) !void
    Summary: Load the specified catalog model and make it the active inference target.
    Description: Hot-swaps the previous model if one is loaded. Validates that the model is installed, supported on this GPU profile, and fits within the VRAM budget before touching Metal.
    Param model_id: Catalog identifier of the managed model to activate.
    Param persist_active: When true, writes the selection to the active-model config file.
    Note: Caller must already hold the shared generation lock.
  - ModelManager.removeManagedModel [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager-metal/#model-manager-remove-managed-model
    Signature: pub fn removeManagedModel(self: *ModelManager, model_id: []const u8, force: bool) !RemoveResult
    Summary: Unload and delete a managed model from both GPU memory and the model store on disk.
    Description: If the model is currently loaded and `force` is false, returns `error.ModelLoadedInGpu`. With `force` true the model is evicted from GPU memory before deletion.
    Param model_id: Catalog identifier of the model to remove.
    Param force: When true, evict the model from GPU memory even if it is active.
    Returns: A `RemoveResult` describing what was unloaded and what was deleted.
    Note: Caller must already hold the shared generation lock.

### Module: Model Manager Runtime
URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager-runtime/
Source: src/server/model_manager_runtime.zig
Code lines: 7
Summary: Backend-selected model manager for the HTTP server.
Overview: This thin shim keeps the HTTP server code importing one stable manager type while build-time backend selection decides whether that implementation comes from the Vulkan runtime or the Apple Silicon Metal runtime.

- LoadSpec [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager-runtime/#load-spec
  Signature: pub const LoadSpec = impl.LoadSpec
  Summary: Specification describing which model to load: a filesystem path, an optional managed-catalog ID, and an optional context-length override.

- ModelManager [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/model-manager-runtime/#model-manager
  Signature: pub const ModelManager = impl.ModelManager
  Summary: Thread-safe manager for the currently active model and inference engine; handles loading, hot-swapping, catalog queries, and VRAM budget enforcement.

### Module: Routes
URL: https://zolotukhin.ai/zinc/docs/zig-api/routes/
Source: src/server/routes.zig
Code lines: 4201
Summary: Route dispatcher and endpoint handlers for the OpenAI-compatible API.
Overview: Handles /v1/chat/completions, /v1/completions, /v1/models, /health, and a built-in chat UI. Supports both streaming (SSE) and non-streaming responses.

- toolCallingEnabled [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/routes/#tool-calling-enabled
  Signature: pub fn toolCallingEnabled() bool
  Summary: Return true if OpenAI-compatible tool calling is enabled.
  Description: Default on. Set `ZINC_TOOL_CALLING=0` (or `false`) to opt out — useful as a kill switch for clients that misbehave when seeing the new `tool_calls` response shape, or for debugging.

- ServerState [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/routes/#server-state
  Signature: pub const ServerState = struct
  Summary: Shared server state tracking active requests, context usage, and generation serialization.
  - ServerState.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/routes/#server-state-init
    Signature: pub fn init(started_at: i64) ServerState
    Summary: Create a new server state anchored to the given UNIX timestamp.
    Param started_at: UNIX timestamp (seconds) of server startup, stored for uptime calculations.
    Returns: Initialized `ServerState` with zeroed counters and an empty chat-reuse cache.
  - ServerState.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/routes/#server-state-deinit
    Signature: pub fn deinit(self: *ServerState) void
    Summary: Release owned resources (chat reuse cache).
  - ServerState.uptimeSeconds [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/routes/#server-state-uptime-seconds
    Signature: pub fn uptimeSeconds(self: *const ServerState, now: i64) u64
    Summary: Return elapsed seconds since the server started.
    Param now: Current UNIX timestamp (seconds) to compare against `started_at`.
    Returns: Non-negative elapsed seconds; clamped to 0 if `now` is before `started_at`.
  - ServerState.snapshot [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/routes/#server-state-snapshot
    Signature: pub fn snapshot(self: *const ServerState, now: i64) HealthSnapshot
    Summary: Atomically capture current request and context counters for the health endpoint.
    Param now: Current UNIX timestamp (seconds) used to compute uptime in the snapshot.
    Returns: `HealthSnapshot` with monotonic reads of all live counters and computed uptime.
  - ServerState.setActiveContextTokens [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/routes/#server-state-set-active-context-tokens
    Signature: pub fn setActiveContextTokens(self: *ServerState, tokens: u32) void
    Summary: Update the active KV-cache token count reported by the health endpoint.
    Param tokens: Number of tokens currently occupying the KV cache.
  - ServerState.clearActiveContext [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/routes/#server-state-clear-active-context
    Signature: pub fn clearActiveContext(self: *ServerState) void
    Summary: Reset the active context token count to zero.
  - ServerState.clearChatReuseCache [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/routes/#server-state-clear-chat-reuse-cache
    Signature: pub fn clearChatReuseCache(self: *ServerState) void
    Summary: Evict all entries from the chat prompt-reuse cache.
  - ServerState.clearChatReuseSession [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/routes/#server-state-clear-chat-reuse-session
    Signature: pub fn clearChatReuseSession(self: *ServerState, session_id: []const u8) void
    Summary: Remove a single session from the chat prompt-reuse cache.
    Param session_id: Opaque session identifier matching the entry to evict.

- handleConnection [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/routes/#handle-connection
  Signature: pub fn handleConnection( conn: *http.Connection, manager: *model_manager_mod.ModelManager, server_state: *ServerState, allocator: std.mem.Allocator, ) !void
  Summary: Handle one HTTP connection: parse request, dispatch to endpoint, send response.
  Param conn: Active client connection to read from and write to.
  Param manager: Model manager used to resolve the active model for inference.
  Param server_state: Shared server metrics and generation serialization lock.
  Param allocator: Allocator for per-request temporaries.

### Module: Runtime
URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime/
Source: src/server/runtime.zig
Code lines: 68
Summary: Backend-specific server runtime aliases and wrappers.
Overview: Keeps the HTTP/routes layer shared across Vulkan and Metal backends.

- is_metal [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime/#is-metal
  Signature: pub const is_metal = gpu.is_metal
  Summary: Whether the active GPU backend is Apple Metal.

- is_vulkan [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime/#is-vulkan
  Signature: pub const is_vulkan = gpu.is_vulkan
  Summary: Whether the active GPU backend is Vulkan.

- supports_model_management [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime/#supports-model-management
  Signature: pub const supports_model_management = gpu.is_vulkan or gpu.is_metal
  Summary: Whether the backend supports loading/unloading models at runtime.

- supports_sampling_controls [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime/#supports-sampling-controls
  Signature: pub const supports_sampling_controls = gpu.is_vulkan or gpu.is_metal
  Summary: Whether the backend supports temperature, top-p, top-k, and repetition penalty.

- supports_runtime_profiling [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime/#supports-runtime-profiling
  Signature: pub const supports_runtime_profiling = gpu.is_vulkan or gpu.is_metal
  Summary: Whether the backend supports GPU kernel profiling during inference.

- tokenizer_mod [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime/#tokenizer-mod
  Signature: pub const tokenizer_mod = @import("../model/tokenizer.zig")
  Summary: Tokenizer module (shared across all backends).

- forward_mod [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime/#forward-mod
  Signature: pub const forward_mod = if (gpu.is_metal) @import("../compute/forward_metal.zig") else @import("../compute/forward.zig")
  Summary: Forward-pass module, selected by the active backend.

- loader_mod [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime/#loader-mod
  Signature: pub const loader_mod = if (gpu.is_metal) @import("../model/loader_metal.zig") else @import("../model/loader.zig")
  Summary: Model-loading module, selected by the active backend.

- model_manager_mod [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime/#model-manager-mod
  Signature: pub const model_manager_mod = if (gpu.is_metal) @import("model_manager_metal.zig") else @import("model_manager.zig")
  Summary: Model-manager module, selected by the active backend.

- InferenceEngine [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime/#inference-engine
  Signature: pub const InferenceEngine = forward_mod.InferenceEngine
  Summary: Backend-specific inference engine that runs the forward pass.

- DecodeState [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime/#decode-state
  Signature: pub const DecodeState = forward_mod.DecodeState
  Summary: Per-sequence decode state (KV cache position, token history, etc.).

- Model [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime/#model
  Signature: pub const Model = loader_mod.Model
  Summary: Loaded model handle (weights, hyperparams, GGUF metadata).

- ModelManager [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime/#model-manager
  Signature: pub const ModelManager = model_manager_mod.ModelManager
  Summary: Manages loading, unloading, and switching between models at runtime.

- SamplingParams [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime/#sampling-params
  Signature: pub const SamplingParams = forward_mod.SamplingParams
  Summary: Token sampling parameters (shared across Vulkan and Metal backends).

- enableLogitsReadback [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime/#enable-logits-readback
  Signature: pub fn enableLogitsReadback(_engine: *InferenceEngine) void
  Summary: Enable logits readback from GPU so sampling can inspect raw logits.
  Description: On Metal (UMA) logits are always CPU-accessible, so this is a no-op.
  Param _engine: Inference engine whose readback mode is updated.

- logitsReadbackEnabled [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime/#logits-readback-enabled
  Signature: pub fn logitsReadbackEnabled(_engine: *const InferenceEngine) bool
  Summary: Return whether logits readback is currently enabled on the engine.
  Description: Always returns `true` on Metal because UMA makes logits CPU-accessible without an explicit readback step.
  Param _engine: Inference engine to query.
  Returns: `true` if the engine will expose logits after each decode step.

- setLogitsReadbackEnabled [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime/#set-logits-readback-enabled
  Signature: pub fn setLogitsReadbackEnabled(_engine: *InferenceEngine, _enabled: bool) void
  Summary: Set the logits readback intent flag on backends that can elide full logit materialization.

- enableProfiling [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime/#enable-profiling
  Signature: pub fn enableProfiling(_engine: *InferenceEngine) !void
  Summary: Enable GPU kernel profiling on the inference engine.
  Description: Supported on both Vulkan and Metal backends; calls the backend's own `enableProfiling` method.
  Param _engine: Inference engine to configure for profiling.
  Returns: An error if the backend's profiling setup fails (e.g. out of GPU resources).

- decodeStep [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime/#decode-step
  Signature: pub fn decodeStep( _engine: *InferenceEngine, _state: *DecodeState, _token_id: u32, _collect_output: bool, ) !void
  Summary: Run a single autoregressive decode step, advancing the KV cache by one token.
  Param _engine: Inference engine that owns the model weights and KV cache.
  Param _state: Per-sequence decode state tracking position and token history.
  Param _token_id: Input token to feed into the model for this step.
  Param _collect_output: When `true`, copy output logits to CPU (Vulkan only; ignored on Metal where logits are always accessible).
  Returns: An error if the GPU submission or synchronisation fails.

- sample [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/runtime/#sample
  Signature: pub fn sample( _engine: *const InferenceEngine, _state: *const DecodeState, _params: SamplingParams, _random: std.Random, ) u32
  Summary: Sample the next token from the model's logit distribution.
  Param _engine: Inference engine holding the current logits.
  Param _state: Decode state used to retrieve generated-token history for repetition penalty.
  Param _params: Sampling configuration (temperature, top-p, top-k, repetition penalty, etc.).
  Param _random: PRNG source for stochastic sampling.
  Returns: The sampled token ID.

## Tool Calling

Tool-use protocol helpers: chat-template-aware tool definitions, argument parsing, and response formatting for function-calling-capable models.
URL: https://zolotukhin.ai/zinc/docs/zig-api#tool-calling

### Module: Tool Format
URL: https://zolotukhin.ai/zinc/docs/zig-api/tool-format/
Source: src/server/tool_format.zig
Code lines: 622
Summary: Pluggable tool-calling format dispatch for chat completions.
Overview: `chatmlToolFormat()` handles Qwen3-family models. `NoopToolFormat` is the silent fallback for any other template kind.

- ToolDefinition [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tool-format/#tool-definition
  Signature: pub const ToolDefinition = struct
  Summary: One tool definition extracted from the request's `tools` array.

- ToolCall [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tool-format/#tool-call
  Signature: pub const ToolCall = struct
  Summary: One parsed tool call extracted from assistant output.

- ParsedAssistantOutput [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tool-format/#parsed-assistant-output
  Signature: pub const ParsedAssistantOutput = struct
  Summary: Result of parsing a non-streaming assistant message: the prose the user should see and any tool invocations the model emitted.
  Description: Returned by `ToolFormat.parseAssistantToolCalls` and consumed by the chat completions response builder when deciding between a `content` reply and a `tool_calls` reply.

- FeedResult [enum]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tool-format/#feed-result
  Signature: pub const FeedResult = enum
  Summary: Disposition of a streaming chunk after the `StreamingDetector` has inspected it.
  Description: The chat completions streamer uses this to decide whether to forward bytes as a `content` delta, swallow them for further inspection, or flush a finished tool call.

- StreamingDetector [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tool-format/#streaming-detector
  Signature: pub const StreamingDetector = struct
  Summary: Streaming-mode tool-call detector.
  Description: The chat completions handler feeds each decoded chunk through this state machine; the detector buffers bytes that might be the start of a `<tool_call>` tag and flushes them either as content deltas or as parsed tool calls. One detector per streaming request.
  - StreamingDetector.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/tool-format/#streaming-detector-deinit
    Signature: pub fn deinit(self: *StreamingDetector) void
    Summary: Free the internal buffers and any pending tool-call payloads.
    Description: Safe to call once at end-of-stream regardless of how many `feed` calls happened.
  - StreamingDetector.feed [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/tool-format/#streaming-detector-feed
    Signature: pub fn feed(self: *StreamingDetector, chunk: []const u8) !FeedResult
    Summary: Push the next decoded chunk into the detector and return how the caller should react.
    Description: The detector retains ownership of `chunk`'s contribution to the internal buffer; callers should drain via `takeContentDelta` and `takePendingToolCall` between feeds. tool call is ready to consume, or the bytes are still being held.
    Param chunk: Newly decoded model bytes.
    Returns: A `FeedResult` indicating whether content is ready to emit, a
  - StreamingDetector.takeContentDelta [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/tool-format/#streaming-detector-take-content-delta
    Signature: pub fn takeContentDelta(self: *StreamingDetector) []const u8
    Summary: Drain pending content bytes.
    Description: The returned slice aliases the detector's internal buffer — consume it before the next feed call (subsequent feeds will overwrite the same allocation). The detector retains ownership and the buffer is freed by deinit.
  - StreamingDetector.takePendingToolCall [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/tool-format/#streaming-detector-take-pending-tool-call
    Signature: pub fn takePendingToolCall(self: *StreamingDetector) ?ToolCall
    Summary: Drain one fully parsed tool call, FIFO order.
    Description: Caller takes ownership of the returned `id`/`name`/`arguments_json` slices and must free them with the same allocator that initialized this detector. Returns null when the queue is empty.
  - StreamingDetector.finalize [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/tool-format/#streaming-detector-finalize
    Signature: pub fn finalize(self: *StreamingDetector) []const u8
    Summary: Flush all remaining buffered bytes as content at end of stream.
    Description: Any bytes still held in the speculative-match buffer are appended to the pending content buffer, and the combined slice is returned. The returned slice aliases the internal buffer; consume before calling deinit.

- ToolFormat [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tool-format/#tool-format
  Signature: pub const ToolFormat = struct
  Summary: Vtable interface to a per-template tool-call format.
  Description: Lets the chat completions path render tool definitions, parse tool calls out of model output, and create matching streaming detectors without knowing whether the active template is ChatML, llama3, or anything else. Concrete implementations are minted via `forTemplate` or the per-format factories `chatmlToolFormat` / `noopToolFormat`.
  - ToolFormat.renderToolDefinitions [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/tool-format/#tool-format-render-tool-definitions
    Signature: pub fn renderToolDefinitions( self: ToolFormat, tools: []const ToolDefinition, buf: *std.ArrayList(u8), allocator: std.mem.Allocator, ) anyerror!void
    Summary: Append the format-specific rendering of `tools` (e.g.
    Description: Qwen's `# Tools\n<tools>...</tools>` block) to `buf`, ready to be spliced into the system message. Noop formats append nothing.
  - ToolFormat.renderToolResultMessage [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/tool-format/#tool-format-render-tool-result-message
    Signature: pub fn renderToolResultMessage( self: ToolFormat, tool_call_id: []const u8, content: []const u8, buf: *std.ArrayList(u8), allocator: std.mem.Allocator, ) anyerror!void
    Summary: Append the format-specific tool-result message (e.g.
    Description: ChatML's `<tool_response>...</tool_response>`) to `buf`. Used when replaying `role: "tool"` history entries into the prompt.
  - ToolFormat.parseAssistantToolCalls [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/tool-format/#tool-format-parse-assistant-tool-calls
    Signature: pub fn parseAssistantToolCalls( self: ToolFormat, model_output: []const u8, allocator: std.mem.Allocator, ) anyerror!ParsedAssistantOutput
    Summary: Split a complete (non-streaming) assistant response into prose plus a list of structured tool calls.
    Description: Allocates the returned slices with the caller's allocator; ownership transfers to the caller.
  - ToolFormat.newStreamingDetector [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/tool-format/#tool-format-new-streaming-detector
    Signature: pub fn newStreamingDetector( self: ToolFormat, allocator: std.mem.Allocator, ) anyerror!*StreamingDetector
    Summary: Create a fresh streaming-mode detector for one chat completion stream.
    Description: Caller owns the returned pointer and must `deinit` + `destroy` it.

- NoopToolFormat [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tool-format/#noop-tool-format
  Signature: pub const NoopToolFormat = struct
  Summary: Silent fallback `ToolFormat` for templates that don't have a tool-call dialect wired in (everything except ChatML today).
  Description: Definition rendering is a no-op, parsing returns the model output verbatim with no tool calls, and the streaming detector treats everything as content.

- noopToolFormat [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tool-format/#noop-tool-format
  Signature: pub fn noopToolFormat() ToolFormat
  Summary: Build a `ToolFormat` backed by `NoopToolFormat`.
  Description: Returned value is cheap to pass around and shares a single static instance.

- forTemplate [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tool-format/#for-template
  Signature: pub fn forTemplate(template_kind: TemplateKind) ToolFormat
  Summary: Pick the right `ToolFormat` for a chat template family.
  Description: ChatML maps to the Qwen3-style `<tool_call>` dialect; everything else falls through to the no-op format (tools field accepted but silently ignored downstream).

- chatmlToolFormat [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/tool-format/#chatml-tool-format
  Signature: pub fn chatmlToolFormat() ToolFormat
  Summary: Build a `ToolFormat` that emits the Qwen3-family `<tool_call>...` dialect.
  Description: Used for any template detected as ChatML. Returned value is cheap to pass around and shares a single static instance.

## CUDA Runtime

CUDA device discovery, context management, device buffers, NVRTC-compiled pipelines, and stream-based command submission for the NVIDIA backend.
URL: https://zolotukhin.ai/zinc/docs/zig-api#cuda-runtime

### Module: Buffer
URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/
Source: src/cuda/buffer.zig
Code lines: 62
Summary: CUDA buffer wrapper — device-local allocations with optional pinned staging.
Overview: Unlike Metal (Apple unified memory), CUDA device memory is NOT CPU-visible; host<->device transfers are explicit (`upload`/`download`), staged through pinned host memory. Mirrors src/metal/buffer.zig.

- CudaBuffer [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#cuda-buffer
  Signature: pub const CudaBuffer = struct
  Summary: CUDA device buffer handle plus optional pinned-host staging mirror.
  - CudaBuffer.devicePtr [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#cuda-buffer-device-ptr
    Signature: pub fn devicePtr(self: *const CudaBuffer) u64
    Summary: Raw device pointer (CUdeviceptr as u64) for kernel arg packing / aliasing.
  - CudaBuffer.contents [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#cuda-buffer-contents
    Signature: pub fn contents(self: *const CudaBuffer) ?[*]u8
    Summary: Pinned host staging pointer, if this buffer was created staged.

- createBuffer [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#create-buffer
  Signature: pub fn createBuffer(ctx: ?*shim.CudaCtx, size: usize) !CudaBuffer
  Summary: Allocate a device-local buffer (the common case for weights/activations/state).
  Param ctx: CUDA context that owns the allocation.
  Param size: Number of bytes to allocate on the device.
  Returns: A `CudaBuffer` with no host staging pointer; use `createBufferStaged` when CPU access is needed.
  Note: Returns `error.CudaBufferAllocFailed` if the shim returns a null handle.

- createBufferStaged [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#create-buffer-staged
  Signature: pub fn createBufferStaged(ctx: ?*shim.CudaCtx, size: usize) !CudaBuffer
  Summary: Allocate a device buffer paired with a pinned-host staging mirror for fast `upload`/`download`.
  Description: The host pointer is exposed via `contents()`.
  Param ctx: CUDA context that owns the allocation.
  Param size: Number of bytes to allocate on both the device and in pinned host memory.
  Returns: A `CudaBuffer` whose `host_ptr` field is non-null; `contents()` returns the pinned staging address.
  Note: Returns `error.CudaBufferAllocFailed` if the shim returns a null handle.

- uploadMmap [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#upload-mmap
  Signature: pub fn uploadMmap(ctx: ?*shim.CudaCtx, host_ptr: *const anyopaque, size: usize) !CudaBuffer
  Summary: Copy an existing host mapping (e.g.
  Description: mmap'd weights) to a new device-local buffer. Unlike Metal's zero-copy wrapMmap, this performs a full host-to-device copy.
  Param ctx: CUDA context that will own the resulting device allocation.
  Param host_ptr: Pointer to the host memory region to copy from (typically an mmap'd file mapping).
  Param size: Number of bytes to transfer.
  Returns: A device-local `CudaBuffer`; `host_ptr` is null (data lives only on device after this call).
  Note: Returns `error.CudaMmapUploadFailed` if the shim returns a null handle.

- aliasBuffer [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#alias-buffer
  Signature: pub fn aliasBuffer(base: *const CudaBuffer, offset: usize, size: usize) !CudaBuffer
  Summary: Create a lightweight view into an existing buffer's device allocation.
  Param base: Parent buffer whose device memory is aliased.
  Param offset: Byte offset from the start of `base`'s device allocation.
  Param size: Number of bytes the alias covers.
  Returns: A `CudaBuffer` with `owns_handle = false`; calling `freeBuffer` on it releases only the wrapper, not the parent's device memory.
  Note: Returns `error.CudaBufferAllocFailed` if the shim returns a null handle.

- freeBuffer [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#free-buffer
  Signature: pub fn freeBuffer(buf: *CudaBuffer) void
  Summary: Free a buffer handle (the shim only releases device memory if this buffer owns it — aliases just free the wrapper).
  Description: Safe with a null handle.

- upload [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#upload
  Signature: pub fn upload(ctx: ?*shim.CudaCtx, buf: *const CudaBuffer, data: []const u8) void
  Summary: Copy bytes from host to device (synchronous on the context stream).
  Param ctx: CUDA context whose stream is used for the transfer.
  Param buf: Destination device buffer; must be at least `data.len` bytes.
  Param data: Source slice on the host.

- download [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#download
  Signature: pub fn download(ctx: ?*shim.CudaCtx, buf: *const CudaBuffer, dst: []u8) void
  Summary: Copy bytes from device to host (synchronous on the context stream).
  Param ctx: CUDA context whose stream is used for the transfer.
  Param buf: Source device buffer; must be at least `dst.len` bytes.
  Param dst: Destination slice on the host.

- uploadAsync [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#upload-async
  Signature: pub fn uploadAsync(ctx: ?*shim.CudaCtx, buf: *const CudaBuffer, data: []const u8) void
  Summary: Async host→device copy (no stream sync).
  Description: Capturable into a CUDA graph; the host side must be pinned (see `allocHost`). @see download(Async) for D2H.

- downloadAsync [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#download-async
  Signature: pub fn downloadAsync(ctx: ?*shim.CudaCtx, buf: *const CudaBuffer, dst: []u8) void
  Summary: Async device→host copy (no stream sync).
  Description: Capturable into a CUDA graph; the destination must be pinned host memory (see `allocHost`).

- allocHost [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#alloc-host
  Signature: pub fn allocHost(comptime T: type, n: usize) ![]T
  Summary: Pinned (page-locked) host allocation of `n` `T` values, required as the host endpoint of an async graph-captured copy.
  Description: Free with `freeHost`.

- freeHost [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/buffer/#free-host
  Signature: pub fn freeHost(slice: anytype) void
  Summary: Free a pinned host allocation from `allocHost`.

### Module: C
URL: https://zolotukhin.ai/zinc/docs/zig-api/c/
Source: src/cuda/c.zig
Code lines: 1
Summary: Shared C import for the CUDA shim — all CUDA backend modules import from here to ensure type identity across compilation units (mirrors src/metal/c.zig).
Overview: Keeping the `@cImport` in one place avoids duplicate opaque C types across Zig compilation units, which is critical for safely passing shim handles between the CUDA device, buffer, pipeline, and command helpers.

- shim [constant]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/c/#shim
  Signature: pub const shim = @cImport(@cInclude("cuda_shim.h"))
  Summary: Raw CUDA shim C bindings (Driver API + NVRTC) imported from cuda_shim.h.

### Module: Command
URL: https://zolotukhin.ai/zinc/docs/zig-api/command/
Source: src/cuda/command.zig
Code lines: 68
Summary: CUDA command wrapper — kernel dispatch and stream/event synchronization (mirrors src/metal/command.zig).
Overview: A CudaCommand wraps the context's CUstream plus a per-command CUevent; `commitAsync`/`wait`/`releaseCompleted` give the same overlap the Metal backend gets, backed by CUDA streams + events.

- CudaCommand [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#cuda-command
  Signature: pub const CudaCommand = struct
  Summary: A recorded stream batch that launches compute kernels on the GPU.
  - CudaCommand.dispatch [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#cuda-command-dispatch
    Signature: pub fn dispatch( self: *CudaCommand, pipe: *const CudaPipeline, grid: [3]u32, block: [3]u32, bufs: []const *const CudaBuffer, push_data: ?*const anyopaque, push_size: usize, shared_bytes: u32, ) void
    Summary: Launch a kernel on this command's stream.
    Description: Bound `bufs` become the leading device-pointer args (capped at 32); `push_data` (push_size bytes) is the trailing by-value push-constant arg.
    Param pipe: Compiled CUDA pipeline (kernel + argument layout) to execute.
    Param grid: 3-D grid dimensions in thread-blocks (x, y, z).
    Param block: 3-D thread-block dimensions (x, y, z).
    Param bufs: Device buffers passed as pointer args before the push constant.
    Param push_data: Pointer to the push-constant struct, or null if unused.
    Param push_size: Byte size of the push-constant struct.
    Param shared_bytes: Dynamic shared memory in bytes to allocate per block.
  - CudaCommand.barrier [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#cuda-command-barrier
    Signature: pub fn barrier(self: *CudaCommand) void
    Summary: Same-stream launches are implicitly ordered; no-op for a single stream.
  - CudaCommand.commitAndWait [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#cuda-command-commit-and-wait
    Signature: pub fn commitAndWait(self: *CudaCommand) void
    Summary: Record completion and block until the stream drains.
  - CudaCommand.commitAsync [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#cuda-command-commit-async
    Signature: pub fn commitAsync(self: *CudaCommand) void
    Summary: Record completion and return immediately; call `wait` later to sync.
  - CudaCommand.wait [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#cuda-command-wait
    Signature: pub fn wait(self: *CudaCommand) void
    Summary: Block on a previously async-committed command's completion event.
  - CudaCommand.releaseCompleted [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#cuda-command-release-completed
    Signature: pub fn releaseCompleted(self: *CudaCommand) void
    Summary: Release a command whose completion is guaranteed by a later queue-ordered synchronization (e.g.
    Description: the caller waited on a subsequent command in the same stream). Frees the shim handle without issuing another wait.

- beginCommand [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/command/#begin-command
  Signature: pub fn beginCommand(ctx: ?*shim.CudaCtx) !CudaCommand
  Summary: Begin a new command (stream batch + completion event) on the given context.
  Description: the underlying stream/event resources.
  Param ctx: Active CUDA context that owns the stream; must not be null.
  Returns: A fresh `CudaCommand` ready for kernel dispatches.
  Note: Returns `error.CudaCommandFailed` if the shim cannot allocate

### Module: Device
URL: https://zolotukhin.ai/zinc/docs/zig-api/device/
Source: src/cuda/device.zig
Code lines: 91
Summary: CUDA device wrapper — NVIDIA GPU backend (mirrors src/metal/device.zig).
Overview: Owns CUDA context init and capability queries used by the loader, diagnostics, and CUDA inference runtime.

- CudaCapabilities [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#cuda-capabilities
  Signature: pub const CudaCapabilities = struct
  Summary: Capability snapshot queried once from the active CUDA device.

- CudaDevice [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#cuda-device
  Signature: pub const CudaDevice = struct
  Summary: Active CUDA device wrapper plus capability metadata used by the backend.
  - CudaDevice.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#cuda-device-init
    Signature: pub fn init(allocator: std.mem.Allocator, device_index: u32) !CudaDevice
    Summary: Initialize a specific CUDA device by index and query its capabilities.
    Param allocator: Allocator stored for future use by the backend.
    Param device_index: Zero-based CUDA device ordinal.
    Returns: Initialised `CudaDevice` with a live context, or `error.CudaInitFailed` if the shim rejects the index.
  - CudaDevice.initBest [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#cuda-device-init-best
    Signature: pub fn initBest(allocator: std.mem.Allocator) !CudaDevice
    Summary: Initialize the highest-compute-capability device (prefer 5090 over 4090).
    Description: Probes up to 16 device indices, selects the one with the largest compute capability value, then opens a final context on that device via `init`.
    Param allocator: Forwarded to `init` for the selected device.
    Returns: Initialised `CudaDevice` for the best device, or `error.CudaNoDevice` if no device is found.
  - CudaDevice.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#cuda-device-deinit
    Signature: pub fn deinit(self: *CudaDevice) void
    Summary: Destroy the active CUDA context.
  - CudaDevice.totalMemory [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#cuda-device-total-memory
    Signature: pub fn totalMemory(self: *const CudaDevice) u64
    Summary: Total device memory (VRAM capacity) in bytes.
  - CudaDevice.freeMemory [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#cuda-device-free-memory
    Signature: pub fn freeMemory(self: *const CudaDevice) u64
    Summary: Currently free device memory in bytes; 0 if the context has been destroyed.
  - CudaDevice.computeCapability [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#cuda-device-compute-capability
    Signature: pub fn computeCapability(self: *const CudaDevice) u32
    Summary: Compute capability encoded as `major*10 + minor` (e.g.
    Description: 120 = sm_120).
  - CudaDevice.smCount [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#cuda-device-sm-count
    Signature: pub fn smCount(self: *const CudaDevice) u32
    Summary: Number of streaming multiprocessors (SMs) on the device.
  - CudaDevice.warpSize [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#cuda-device-warp-size
    Signature: pub fn warpSize(self: *const CudaDevice) u32
    Summary: Threads per warp (32 on all current NVIDIA hardware).
  - CudaDevice.maxSharedMemPerBlock [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#cuda-device-max-shared-mem-per-block
    Signature: pub fn maxSharedMemPerBlock(self: *const CudaDevice) u64
    Summary: Maximum shared memory per block available with opt-in dynamic allocation, in bytes.
  - CudaDevice.name [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/device/#cuda-device-name
    Signature: pub fn name(self: *const CudaDevice, buf: []u8) []const u8
    Summary: Copy the device name into `buf` and return the NUL-trimmed slice.
    Param buf: Caller-supplied scratch buffer; 64–256 bytes is typically sufficient.
    Returns: Slice into `buf` containing the device name without a trailing NUL, or an empty slice if the context has been destroyed.

### Module: Pipeline
URL: https://zolotukhin.ai/zinc/docs/zig-api/pipeline/
Source: src/cuda/pipeline.zig
Code lines: 35
Summary: CUDA compute pipeline wrapper — NVRTC-compiled CUfunction (mirrors src/metal/pipeline.zig).
Overview: Compiles a `.cu` source string for the running device's arch (sm_XY) or loads a precompiled cubin/PTX image. Each pipeline holds a `CUmodule` + `CUfunction` pair obtained from the C shim. Use `createPipeline` for JIT compilation via NVRTC or `createPipelineFromImage` when an offline-compiled cubin/PTX blob is available. Free with `freePipeline` when done.

- CudaPipeline [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/pipeline/#cuda-pipeline
  Signature: pub const CudaPipeline = struct
  Summary: A compiled CUDA kernel ready for dispatch.

- createPipeline [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/pipeline/#create-pipeline
  Signature: pub fn createPipeline(ctx: ?*shim.CudaCtx, cu_source: [*:0]const u8, fn_name: [*:0]const u8) !CudaPipeline
  Summary: NVRTC-compile `cu_source` and resolve `fn_name` for dispatch.
  Param ctx: Active CUDA context; must not be null.
  Param cu_source: Null-terminated CUDA C source string passed directly to NVRTC.
  Param fn_name: Null-terminated name of the kernel function to extract from the compiled module.
  Returns: A `CudaPipeline` with populated `max_threads` and `shared_mem` fields, or `error.CudaPipelineCreateFailed`.

- createPipelineFromImage [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/pipeline/#create-pipeline-from-image
  Signature: pub fn createPipelineFromImage(ctx: ?*shim.CudaCtx, image: [*]const u8, image_size: usize, fn_name: [*:0]const u8) !CudaPipeline
  Summary: Load a kernel from a precompiled cubin/PTX image (offline nvcc path).
  Param ctx: Active CUDA context; must not be null.
  Param image: Pointer to the raw cubin or PTX image bytes.
  Param image_size: Byte length of `image`.
  Param fn_name: Null-terminated name of the kernel function to locate in the loaded module.
  Returns: A `CudaPipeline` with populated `max_threads` and `shared_mem` fields, or `error.CudaPipelineCreateFailed`.

- setMaxDynamicShared [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/pipeline/#set-max-dynamic-shared
  Signature: pub fn setMaxDynamicShared(pipe: *CudaPipeline, bytes: u32) void
  Summary: Opt this kernel into a larger dynamic shared-memory cap (Ada/Blackwell).
  Description: default 48 KB barrier by calling `cuFuncSetAttribute` on the shim side.
  Param pipe: Pipeline whose dynamic shared-memory limit to raise.
  Param bytes: New maximum dynamic shared memory per block in bytes.
  Note: No-op when `pipe.handle` is null. On Ada/Blackwell this lifts the

- freePipeline [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/pipeline/#free-pipeline
  Signature: pub fn freePipeline(pipe: *CudaPipeline) void
  Summary: Release the pipeline handle.
  Description: Safe to call with a null handle.

### Module: Smoke
URL: https://zolotukhin.ai/zinc/docs/zig-api/smoke/
Source: src/cuda/smoke.zig
Code lines: 77
Summary: Standalone smoke test for the ZINC CUDA backend Zig wrapper layer. Drives the GPU entirely through device.zig / buffer.zig / pipeline.zig / command.zig (which wrap cuda_shim.c) — proving the Zig<->CUDA seam: device select, staged buffers + H2D/D2H, NVRTC runtime compile, the buffers+push dispatch ABI, and both sync and async commit paths.
Overview: Build (on the box): ~/zig-0.15.2/zig build-exe smoke.zig cuda_shim.c \ -I. -I/usr/local/cuda/include -lc \ -L/usr/local/cuda/lib64 -L/usr/lib/wsl/lib -lcuda -lnvrtc \ -rpath /usr/local/cuda/lib64 -femit-bin=smoke_zig

- main [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/smoke/#main
  Signature: pub fn main() !void
  Summary: Run the CUDA Zig<->shim smoke test end to end and report PASS/FAIL.
  Description: Selects the best device, then exercises the full seam: a `vadd` kernel via the synchronous commit path and a `dp4a` kernel via the async commit path, checking both results.
  Returns: `error.SmokeFailed` if any computed value mismatches its expected output.

### Module: Dbg Cuda
URL: https://zolotukhin.ai/zinc/docs/zig-api/dbg-cuda/
Source: src/dbg_cuda.zig
Code lines: 2178
Summary: CUDA forward-pass debug harness for the qwen35 hybrid-SSM model. Two modes:
Overview: zig build cuda-dbg -- <token> [model.gguf] Per-layer residual-norm dump at pos 0 (used to pinpoint the attention gate bug: diff vs a reference implementation eval-callback `l_out-N` reference).
Overview: zig build cuda-dbg -- gen <id,id,...> <ngen> [model.gguf] Autoregressive greedy generation from a prompt token-id list. Prefills the ids (exercising pos>0 RoPE + multi-entry attention + SSM state carry), then greedily emits ngen tokens. Diff GEN_IDS vs `/tmp/gen` (the reference implementation greedy) to validate the full decode path beyond pos 0.
Overview: Read-only w.r.t. the engine — uses only public ForwardCuda methods.

- main [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/dbg-cuda/#main
  Signature: pub fn main() !void

### Module: Loadtest Cuda
URL: https://zolotukhin.ai/zinc/docs/zig-api/loadtest-cuda/
Source: src/loadtest_cuda.zig
Code lines: 93
Summary: Standalone load-test for src/model/loader_cuda.zig.
Overview: Drives only the CUDA loader path: select the best device, mmap + parse a GGUF, upload every tensor to the GPU, and report the parsed config, the tensor count, GPU free-mem before/after (to confirm ~model-size uploaded), a spot-check of 3 tensors, and a CPU embedding-row dequant. Independent of forward_cuda / gpu dispatch so the loader can be validated on its own.
Overview: Rooted at src/ (module path) so it can import both model/* and cuda/* — exactly like src/main.zig. The whole thing is one Zig module, which keeps the loader's internal `../cuda/*` imports resolvable.
Overview: Build + run (on the box): cd ~/zinc5090 && CUDA_HOME=/usr/local/cuda \ ~/zig-0.15.2/zig build cuda-loadtest -Dbackend=cuda -- <model.gguf>

- main [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/loadtest-cuda/#main
  Signature: pub fn main() !void
  Summary: Load a GGUF onto the GPU via loader_cuda and print a structured report.
  Description: surfaces a nonzero exit on failure.
  Returns: Propagates loader errors (init/open/parse/upload) so the build step

### Module: Run Cuda
URL: https://zolotukhin.ai/zinc/docs/zig-api/run-cuda/
Source: src/run_cuda.zig
Code lines: 120
Summary: Standalone CUDA greedy-decode driver for the qwen35 forward pass.
Overview: Loads the GGUF onto the GPU via loader_cuda, builds the forward state in src/compute/forward_cuda.zig, and runs a single greedy decode step for a fixed token, printing the predicted token id, a hidden-state sanity dump, and the top-5 logits. Independent of the gpu/ dispatch interface so the CUDA forward pass can be brought up incrementally.
Overview: Rooted at src/ (module path) so it reaches both model/* and cuda/* and compute/* — exactly like src/main.zig. The whole thing is one Zig module so the loader's and forward pass's internal `../cuda/*` imports resolve.
Overview: Build + run (on the box): cd ~/zinc5090 && CUDA_HOME=/usr/local/cuda \ ~/zig-0.15.2/zig build cuda-run -Dbackend=cuda -- [token] [milestone] [model.gguf] milestone: v0 (tail only), v1 (one attn L3 + one ssm L0 + ffn), v2 (full 32 layers)

- main [function]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/run-cuda/#main
  Signature: pub fn main() !void

## CUDA Multi-Tenant Serving Engine

Continuous-batching serving worker, request registry, per-token streaming channels, and GPU-owned decode loop for concurrent CUDA inference.
URL: https://zolotukhin.ai/zinc/docs/zig-api#cuda-multi-tenant-serving-engine-effort-28-increment-3-3b

### Module: Cuda Serve
URL: https://zolotukhin.ai/zinc/docs/zig-api/cuda-serve/
Source: src/server/cuda_serve.zig
Code lines: 285
Summary: One GPU **worker thread** runs the continuous-batching loop (admit → prefill → `decodeBatch` → evict); many transport (HTTP) handler threads `submit` requests concurrently and **stream each request's own tokens incrementally** as the worker produces them. This is the threading model proven token-identical to N isolated single-sequence runs by the `dbg_cuda serve` harness (3a); 3b factors it into a reusable engine and adds the per-token streaming registry the HTTP/SSE transport needs.
Overview: ADDITIVE: the production single-sequence `decodeStep`/`prefillBatched` path is untouched. The engine REUSES `Scheduler` + `ForwardGemma.decodeBatch` (proven in increments 1+2); the only genuinely-new code here is the cross-thread result registry + the GPU worker loop.
Overview: Thread-safety model (identical to the 3a proof): * ALL GPU work (`decodeBatch`, prefill) runs ONLY on the worker thread. The CUDA shim rebinds the context per call (`cuCtxSetCurrent` at every entry), so a single GPU-owning thread needs no extra ceremony. * Cross-thread mutable state = the scheduler `pending` FIFO (handlers append via `enqueue`; worker drains via `admitNext`) + the per-request channel registry. Both are guarded by ONE `mutex`. Slot state (prefill / decode / append / release) and the scratch slices are worker-only and lock-free. * Each sequence's tokens depend only on its own slot KV + position (proven isolated in increment 1), so the nondeterministic admit/interleave ORDER across handler threads cannot change any sequence's output.

- Forward [union]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cuda-serve/#forward
  Signature: pub const Forward = union(enum)
  Summary: Architecture-dispatched GPU forward held by the serving engine.
  Description: gemma4 dense (`ForwardGemma`) and the qwen35/36 hybrid-SSM family (`ForwardCuda`) expose the SAME batched serving primitives — `decodeBatch(tokens,positions,slots,out)` and per-sequence slot-state alloc — only under different method names, so the engine drives EITHER through this thin union. Effort 28 increment 4 (qwen serving): the Scheduler / ReqChannel / worker threading are model-agnostic; only these calls differ. The forward is owned by the caller (its frame outlives the engine).

- ReqChannel [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cuda-serve/#req-channel
  Signature: pub const ReqChannel = struct
  Summary: Per-request published-token channel.
  Description: The handler thread that submitted the request OWNS this struct (it lives on the handler's stack/frame); the worker appends generated tokens + flips `done`/`failed` under the engine mutex and broadcasts. Registered by request id in `ServeEngine.registry`. ALL fields are touched only under `ServeEngine.mutex` (the worker may realloc `tokens` while the handler drains it, so the handler must copy out under the same lock).

- Chunk [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cuda-serve/#chunk
  Signature: pub const Chunk = struct
  Summary: Result of `nextChunk`: how many fresh tokens were copied into the caller's buffer and whether the stream is now fully drained.

- ServeEngine [struct]
  URL: https://zolotukhin.ai/zinc/docs/zig-api/cuda-serve/#serve-engine
  Signature: pub const ServeEngine = struct
  - ServeEngine.init [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cuda-serve/#serve-engine-init
    Signature: pub fn init( allocator: std.mem.Allocator, fwd: Forward, nslots: u32, slot_ctx: u32, eos: u32, ) !ServeEngine
    Summary: Allocate slot-based per-sequence state + a scheduler with `nslots` concurrent slots, each `slot_ctx` tokens deep.
    Description: The forward (`fwd`) must already be initialized; it may be EITHER a gemma or qwen forward (dispatched by `Forward`).
  - ServeEngine.deinit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cuda-serve/#serve-engine-deinit
    Signature: pub fn deinit(self: *ServeEngine) void
  - ServeEngine.start [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cuda-serve/#serve-engine-start
    Signature: pub fn start(self: *ServeEngine) !void
    Summary: Spawn the GPU worker thread.
  - ServeEngine.shutdown [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cuda-serve/#serve-engine-shutdown
    Signature: pub fn shutdown(self: *ServeEngine) void
    Summary: Signal the worker to drain outstanding work and exit, then join it.
  - ServeEngine.submit [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cuda-serve/#serve-engine-submit
    Signature: pub fn submit(self: *ServeEngine, prompt_tokens: []const u32, max_tokens: u32, chan: *ReqChannel) !u64
    Summary: Submit a request: register its channel, enqueue the prompt, wake the worker.
    Description: The caller MUST keep `prompt_tokens` alive until the request finishes (the `Request` borrows the slice), and call `finish(id)` afterward.
    Returns: the request id (used to wait/finish).
  - ServeEngine.nextChunk [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cuda-serve/#serve-engine-next-chunk
    Signature: pub fn nextChunk(self: *ServeEngine, chan: *ReqChannel, dst: []u32) Chunk
    Summary: Block until fresh tokens are available for `chan` or it finishes, then copy up to `dst.len` newly-generated tokens into `dst` (all under the lock, since the worker may realloc `chan.tokens` concurrently).
    Description: Returns the count copied and whether the stream is now fully drained. Loop calling this until `finished`.
  - ServeEngine.finish [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cuda-serve/#serve-engine-finish
    Signature: pub fn finish(self: *ServeEngine, id: u64, chan: *ReqChannel) void
    Summary: Deregister + free a finished request's channel.
    Description: Call once `done`/`failed` has been observed and all tokens drained.
  - ServeEngine.statsJson [method]
    URL: https://zolotukhin.ai/zinc/docs/zig-api/cuda-serve/#serve-engine-stats-json
    Signature: pub fn statsJson(self: *ServeEngine, buf: []u8) ![]const u8
    Summary: Write the cumulative throughput counters as JSON into `buf`.
    Description: Lock-free (atomic loads) so `/stats` never contends the worker. The gate diffs two snapshots around each B-concurrent phase → pure decode tok/s + occupancy.