{
  "schema": "fak.build-variants.v1",
  "doc": [
    "The single-source taxonomy of every supported optional build-tag combo (#3712, epic #3708).",
    "CI's build-matrix.yml derives its compile-check matrix from this file (via `fak-dev build-matrix --emit-gha-matrix`):",
    "add a variant here and it enrolls in the gate automatically — there is no hand-maintained",
    "YAML list to drift (the DRY lesson from the release flag string, solved for flags by",
    "scripts/build.sh / #3709). Classification, not re-implementation: the invariant that every",
    "`import \"C\"` file sits behind an opt-in //go:build tag is enforced by internal/architest",
    "(that fencing is WHY the default build can be pure-Go and reproducible), and the arch/device",
    "taxonomy for NEW backends is generated by `fak backend scaffold` (cmd/fak/backendscaffold.go",
    "+ internal/compute/scaffold.go). gate values: 'matrix' = trunk-gating in build-matrix.yml;",
    "'advisory' = run in build-matrix.yml with continue-on-error (a wip_ fence hides code that",
    "may legitimately not compile against committed symbols — the internal/buildwitness +",
    "internal/wipfence contract — so it is witnessed, never trunk-gating); 'external' = owned by",
    "a toolchain-specific workflow; 'manual' = dispatch-only GPU runner; 'none' = UNWITNESSED",
    "today, named here so the gap is visible instead of implicit."
  ],
  "release_targets": [
    { "goos": "linux", "goarch": "amd64" },
    { "goos": "linux", "goarch": "arm64" },
    { "goos": "darwin", "goarch": "amd64" },
    { "goos": "darwin", "goarch": "arm64" },
    { "goos": "windows", "goarch": "amd64" }
  ],
  "variants": [
    {
      "name": "default",
      "tags": "",
      "cgo_enabled": "0",
      "default_inclusion": "default",
      "target_os_arch": "all",
      "toolchain_requirements": "Go 1.26+ (pure Go, CGO_ENABLED=0)",
      "constraint": "(none — the shipped static pure-Go binary)",
      "class": "pure-go",
      "gate": "matrix",
      "witness": "build-matrix.yml cross-builds every release_targets entry; reproducible.yml double-build byte-identity; cuda-build.yml static job's no-cgo-leak guard"
    },
    {
      "name": "darwin-arm64",
      "tags": "",
      "cgo_enabled": "0",
      "default_inclusion": "default",
      "target_os_arch": "darwin/arm64",
      "toolchain_requirements": "Go 1.26+ cross-compiler (pure Go)",
      "constraint": "darwin && arm64",
      "class": "pure-go",
      "gate": "matrix",
      "witness": "build-matrix.yml pure-Go cross-build"
    },
    {
      "name": "linux-amd64",
      "tags": "",
      "cgo_enabled": "0",
      "default_inclusion": "default",
      "target_os_arch": "linux/amd64",
      "toolchain_requirements": "Go 1.26+ (pure Go)",
      "constraint": "linux && amd64",
      "class": "pure-go",
      "gate": "matrix",
      "witness": "build-matrix.yml pure-Go cross-build"
    },
    {
      "name": "windows-amd64",
      "tags": "",
      "cgo_enabled": "0",
      "default_inclusion": "default",
      "target_os_arch": "windows/amd64",
      "toolchain_requirements": "Go 1.26+ cross-compiler (pure Go)",
      "constraint": "windows && amd64",
      "class": "pure-go",
      "gate": "matrix",
      "witness": "build-matrix.yml pure-Go cross-build"
    },
    {
      "name": "wip_sessionfleet",
      "tags": "wip_sessionfleet",
      "cgo_enabled": "0",
      "default_inclusion": "opt-in",
      "target_os_arch": "all",
      "toolchain_requirements": "Go 1.26+ (pure Go)",
      "constraint": "wip_sessionfleet",
      "class": "pure-go-wip",
      "gate": "advisory",
      "witness": "build-matrix.yml advisory lane (continue-on-error): red means the fenced WIP has drifted from committed symbols, which the wipfence contract permits — visible, not trunk-gating"
    },
    {
      "name": "cuda",
      "tags": "cuda",
      "cgo_enabled": "1",
      "default_inclusion": "opt-in",
      "target_os_arch": "linux/amd64",
      "toolchain_requirements": "Go 1.26+, C compiler (gcc/clang), NVIDIA CUDA Toolkit (nvcc, cudart, cublas)",
      "constraint": "cuda",
      "class": "cgo",
      "gate": "external",
      "witness": "cuda-build.yml: go vet -tags cuda (toolkit-free header) + nvcc tier compiling kernels and linking go build -tags cuda against stub libs"
    },
    {
      "name": "cuda-nccl",
      "tags": "cuda nccl",
      "cgo_enabled": "1",
      "default_inclusion": "opt-in",
      "target_os_arch": "linux/amd64",
      "toolchain_requirements": "Go 1.26+, CUDA Toolkit, NVIDIA NCCL headers/libraries",
      "constraint": "cuda && nccl",
      "class": "cgo",
      "gate": "none",
      "witness": "UNWITNESSED today — needs NCCL headers/stubs in the nvcc tier; named follow-on of #3712"
    },
    {
      "name": "cuda-windows",
      "tags": "cuda",
      "cgo_enabled": "1",
      "default_inclusion": "opt-in",
      "target_os_arch": "windows/amd64",
      "toolchain_requirements": "Go 1.26+, MSVC C++ toolchain, NVIDIA CUDA Toolkit for Windows",
      "constraint": "cuda && windows",
      "class": "cgo",
      "gate": "manual",
      "witness": "windows-cuda.yml (workflow_dispatch, self-hosted GPU runner)"
    },
    {
      "name": "vulkan-windows",
      "tags": "vulkan",
      "cgo_enabled": "1",
      "default_inclusion": "opt-in",
      "target_os_arch": "windows/amd64",
      "toolchain_requirements": "Go 1.26+, C compiler (MinGW/MSVC), LunarG Vulkan SDK, AMD Vulkan driver",
      "constraint": "vulkan && windows",
      "class": "cgo",
      "gate": "none",
      "witness": "UNWITNESSED today — needs a Windows cgo runner + a libfakvulkan.a stub; named follow-on of #3712"
    },
    {
      "name": "metal",
      "tags": "",
      "cgo_enabled": "1",
      "default_inclusion": "opt-in",
      "target_os_arch": "darwin/arm64",
      "toolchain_requirements": "macOS 14+, Xcode / Apple Clang, Metal & MetalPerformanceShaders frameworks",
      "constraint": "darwin && arm64 && cgo",
      "class": "cgo",
      "gate": "none",
      "witness": "UNWITNESSED today — needs a macOS arm64 cgo runner; named follow-on of #3712"
    }
  ]
}