fuel-dispatch 0.20.0

Dispatch infrastructure for fuel: KernelBindingTable, per-backend registration wrappers, CompiledNode + compile_node, ExecutionPlan + compile_plan + resolve_kernel, FusedKernelRegistry, PipelinedExecutor. The layer that takes a graph and runs it against registered backends. Extracted from fuel-memory 2026-05-31.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172

[package]

categories.workspace = true

description = "Dispatch infrastructure for fuel: KernelBindingTable, per-backend registration wrappers, CompiledNode + compile_node, ExecutionPlan + compile_plan + resolve_kernel, FusedKernelRegistry, PipelinedExecutor. The layer that takes a graph and runs it against registered backends. Extracted from fuel-memory 2026-05-31."

edition.workspace = true

keywords.workspace = true

license.workspace = true

name = "fuel-dispatch"

repository.workspace = true

version.workspace = true



[dependencies]

fuel-ir = { workspace = true }

fuel-backend-contract = { workspace = true }

fuel-cpu-backend = { workspace = true }

fuel-hardware = { workspace = true }

fuel-cuda-backend = { workspace = true, optional = true }

fuel-graph = { workspace = true }

# The §6.20 shape-expression grammar's permanent home; `fkc::shape_expr` is a

# re-export shim over it (Increment C slice 1, T1). Unconditional — FKC is

# unconditional core infrastructure.

fuel-kernel-seam-types = { workspace = true }

# kiss-ref advisory cross-check (cuda-gated verify path only) — see the `cuda` feature.

fuel-kiss-ref-backend = { path = "../fuel-kiss-ref-backend", version = "0.20.0", optional = true }

# kiss-ref-core (github.com/ThinkersJournal/kiss-ref, crates.io "0.4") — the SINGLE

# cross-project source of truth for the ULP-distance metric. `fkc::verify::ulp::

# ulp_distance` delegates to `kiss_ref_core::ulp_distance_f32` so Fuel's verify stack

# and any other "KISS-speaking" project compare floats byte-for-byte identically

# (previously a Fuel-internal copy that had drifted on NaN handling). NON-optional:

# `mod ulp;` is always compiled and its unit tests run under a plain `cargo test`.

# `no_std`, small; already present transitively via fuel-kiss-ref-backend. "0.4"

# tracks non-breaking 0.4.z per kiss-ref's release discipline (same as the adapter).

kiss-ref-core = "0.4"

fuel-memory = { workspace = true }

fuel-vulkan-backend = { workspace = true, optional = true }

# Baracuda's shipped `structure_key` keyer (pure-Rust types crate — no nvcc).

# Pulled by the `cuda` feature so the telemetry `BaracudaStructureKeyProvider`

# can call it; already present transitively via fuel-cuda-backend.

baracuda-kernels-types = { workspace = true, optional = true }

# The JIT-on-request envelope — only under `jit` (the adopt-glue seam). The core

# dispatch layer stays free of it (adopt_runtime_fused takes resolved parts).

fuel-kernel-seam = { workspace = true, optional = true }

# kiss-ref's pure op vocabulary — only under `jit`, so the CPU-side advisory ULP

# band (`jit_ingest::advisory_ulp_band`) reads the per-op §6.8 ceilings from

# kiss-ref's OWN API (`Op::ulp_ceiling`) without pulling the (cuda-gated)

# fuel-kiss-ref-backend adapter.

#

# FROM CRATES.IO, NOT A GIT REV — this took CI down completely and the reason is

# worth keeping. It was pinned to a rev in `ThinkersJournal/kiss-ref`, which is

# PRIVATE. `optional = true` did NOT contain the damage: cargo resolves the WHOLE

# dependency graph, optional entries included, BEFORE it compiles anything, so it

# must load that source no matter which features are selected. A dependency

# nobody enabled failed every `Check` and `Test` job on every OS at resolution —

# and it was invisible locally, because a developer box has warm `~/.cargo/git`

# and credentials. A clean checkout is the only environment that can see it, and

# CI is the only environment that is one. (The error even misdirects: it reads

# `revision e8ae0b58… not found`, but the rev exists — that is the auth failure

# wearing a missing-object message.)

#

# "0.4" matches `fuel-kiss-ref-backend/Cargo.toml`, so the two are now in

# lockstep via a PUBLIC registry rather than a private rev — same intent as

# before, minus the ability to break every build for anyone outside the org.

kiss-ops-vocab = { version = "0.4", optional = true }

# NVRTC (crates.io-pinned, no ../baracuda checkout) — only under `cuda`, for the

# tests/jit_synth_kernel_live.rs on-device JIT-load test, which compiles a

# scalar-ABI PTX kernel at test time.

baracuda-nvrtc = { workspace = true, optional = true }

# The live JIT synthesizer, only under `jit-synth` (which also enables cuda+jit,

# providing the nvrtc + seam features cuda-emit's `seam`/`nvrtc` need). Crates.io

# (exact pin) — NOT a ../baracuda path dep, so it honors the reference-only rule.

baracuda-cuda-emit = { workspace = true, optional = true, features = ["seam", "nvrtc"] }

bytemuck = { workspace = true }

half = { workspace = true }

smallvec = { workspace = true }

thiserror = { workspace = true }

tracing = { workspace = true }

# FKC kernel-contract importer deps. FKC is unconditional core infrastructure

# (the CPU elementwise-binary family registers from its contract in

# `register_cpu_kernels`), so serde / serde_yaml_ng / serde_json are always

# compiled — no feature gate.

serde = { workspace = true }

serde_yaml_ng = { workspace = true }

# serde_json is unconditional core infrastructure: the FKC verification ledger

# (`fkc/verify/ledger.rs`) parses a git-checked-in JSON ledger via `include_str!`

# at import time in every build (u64 revision hashes exceed 2^53, so f64-based

# YAML parsing would lose precision — serde_json parses u64 natively). Also used

# by the (optional) `telemetry` feature's JSONL emission.

serde_json = { workspace = true }



[target.'cfg(any(target_os = "macos", target_os = "ios"))'.dependencies]

fuel-metal-backend = { workspace = true, optional = true }



[dev-dependencies]

# QMatMul tests construct Q4_0 weight blocks directly.

fuel-quantized = { path = "../fuel-quantized" }

# Conv2D live-GPU tests compare against fuel-conv's CPU reference.

fuel-conv = { path = "../fuel-conv" }

# Telemetry sink tests write JSONL to a scratch dir (atomic tmp+rename).

tempfile = { workspace = true }

# GAP-224: live-GPU tests assert the machine-wide GPU mutex via require_gpu_run_lock.

fuel-test-support = { path = "../fuel-test-support" }



[features]

# FKC is NOT a feature — it is unconditional core infrastructure. serde /

# serde_yaml_ng / serde_json are always-on deps and `pub mod fkc` is unconditional. There is

# deliberately no `fkc` gate: once a family's hand-written registration is

# deleted on migration to its contract (the CPU elementwise-binary family

# already is — see `register_cpu_kernels`), a build without the importer would

# silently lose that family. No gate ⇒ no such doomed config.

default = []

# Baracuda's PURE HOST type vocabulary (`ElementKind`, `OperandDesc`,

# `structure_key_token`). NOT the kernel forge: `baracuda-kernels-types` has

# `build = false` and does not depend on `baracuda-kernels-sys`, so enabling

# this compiles NO CUDA kernels. (It does still reach `baracuda-cuda-sys`, whose

# build script is a 321-byte placeholder emitting two `rerun-if-env-changed`

# lines, with bindings pre-generated and vendored in-tree.)

#

# CORRECTED 2026-08-28 — THIS COMMENT USED TO END *"so the CUDA SDK must be

# present, but nothing is forged."* THE SECOND HALF IS RIGHT AND THE FIRST IS

# MEASURABLY WRONG FOR A `check`. A GitHub-hosted `ubuntu-latest` has NO CUDA SDK,

# and `cargo check -p fuel-dispatch --features telemetry,baracuda-types

# --all-targets` COMPILED THERE — run 33128700330, read at STEP level, which is

# what converts the GAP-247 leg from unverified into real coverage per GAP-181.

#

# SCOPE, STATED BECAUSE THE MEASUREMENT HAS ONE: this is proven for `check`.

# Whether a LINK needs the SDK is untested in either direction — do not read the

# correction as wider than the run that produced it.

#

# WHY THE FALSE HALF MATTERED: a capability claim that overstates a precondition

# does not fail loudly, IT STOPS PEOPLE TRYING — it is why nobody put this cell in

# CI. Same shape as CLAUDE.md's GAP-016 "mkl/aocl are unbuildable here", which was

# false and hid real rot behind it.

#

# WHY THIS EXISTS AS ITS OWN FEATURE RATHER THAN RIDING `cuda` OR `jit`.

# `telemetry/baracuda_provider.rs` needs exactly this crate and nothing else

# CUDA-ish, but was gated on `cuda` — which additionally pulls

# `fuel-cuda-backend` and therefore the kernel forge. That made a `cargo test`

# over a pure-host keying function cost a full forge build (measured: 1h51m on

# a cold cache, ~14s once the gate is narrowed), and it is a cost paid EXACTLY

# on a baracuda bump, i.e. precisely when someone is verifying something.

#

# Gating the module on `any(cuda, jit)` was rejected deliberately: that would be

# correct only because `jit` happens to list this dep, a justification living in

# ANOTHER feature's list that could expire silently if JIT stopped needing it —

# the module would quietly stop compiling under the narrow gate with no error.

# Naming the real requirement makes the gate's coverage unbreakable from

# elsewhere. (GAP-173.)

#

# Feature resolution is UNCHANGED for every existing consumer: `cuda` and `jit`

# both already listed `dep:baracuda-kernels-types` directly and now go through

# this instead.

baracuda-types = ["dep:baracuda-kernels-types"]

# Per-backend dispatch wrappers. Feature flags propagate the same shape

# fuel-memory used: each GPU backend's registration entry-point is

# gated behind its feature.

cuda = ["dep:fuel-cuda-backend", "baracuda-types", "dep:baracuda-nvrtc", "fuel-memory/cuda", "fuel-hardware/cuda", "dep:fuel-kiss-ref-backend"]

vulkan = ["dep:fuel-vulkan-backend", "fuel-memory/vulkan", "fuel-hardware/vulkan"]

metal = ["dep:fuel-metal-backend", "fuel-memory/metal"]

# Baracuda dispatch-telemetry / miss-reporting emission (docs/session-prompts/

# baracuda-telemetry-plan.md). Reads the already-retained Judge timings; emits

# DispatchRecord/MissRecord JSONL. Default OFF; pulls fuel-ir/serde so the

# ImplId basis tuple (OpKind/DType/BackendId) serializes. (serde itself is now

# an unconditional dep, so it is no longer listed here.)

telemetry = ["fuel-ir/serde"]

# JIT-on-request adopt glue (the seam-consumption site): synthesize -> take_kernel

# -> load kernel (caller-provided CUDA seam) -> adopt_runtime_fused. Pulls the

# envelope crate + baracuda's OperandDesc (ElementKind). Default OFF.

jit = ["dep:fuel-kernel-seam", "baracuda-types", "dep:kiss-ops-vocab"]

# The LIVE JIT loop on published crates: jit + cuda + the real BaracudaSynthesizer

# (baracuda-cuda-emit, seam+nvrtc). Enables the on-device test that drives

# synthesize -> take_kernel -> load_synth_kernel -> launch with Baracuda's own

# generated kernel (not a mock). Needs the CUDA toolchain (nvrtc). Default OFF.

jit-synth = ["jit", "cuda", "dep:baracuda-cuda-emit"]