[FEA] cuda.core: adopt nvFatbin for multi-arch fat binary assembly

Summary

cuda.bindings.nvfatbin (available since cuda-bindings 12.9.x) is not used anywhere in cuda.core
product code today — it only appears as a test helper that builds a two-arch fatbin to exercise
ObjectCode.from_fatbin:
https://github.com/NVIDIA/cuda-python/blob/c000331de6c37aa4565af74b001271ffcf6d5c99/cuda_core/tests/test_module.py#L144-L175

cuda.core covers the consume side of fat binaries
(ObjectCode.from_fatbin)
but has no produce side: to target several architectures, users must juggle N per-arch
ObjectCodes or shell out to the fatbinary CLI. nvFatbin closes this gap in-process.

Use cases:

• compile per arch (CUBIN/PTX/LTO-IR) and ship one artifact; PTX/LTO-IR entries keep JIT
  forward-compatibility on newer GPUs
• AOT kernel caches / packaging: one fatbin per kernel suite instead of per-arch files
• bundling Tile IR (nvFatbinAddTileIR) once #1322 / #1434 land

Underlying C APIs to cover

The entire libnvfatbin surface (pythonic names from
cuda.bindings.nvfatbin @ v13.3.1):

The bindings load libnvfatbin lazily, so each entry point also requires a new-enough runtime
library — option/entry-point support must be version-gated with actionable error messages,
in the spirit of #337.

Design sketch (draft — needs design-meeting review)

[!IMPORTANT]
The sketch below is a starting point only, not a settled design. API shape, names, and
scope should all be reviewed in the cuda.core design meeting before implementation.

Option A — one-shot constructor, no intermediate handle exposed:

code: ObjectCode = ObjectCode.from_parts(     # all names TBD
    [objcode_sm100a,                          # ObjectCode in, kind/arch from metadata...
     (ptx, "ptx", "sm_120")],                 # ...or raw bytes + explicit kind/arch
    options=...,
)                                             # ObjectCode with code_type="fatbin"

Option B — a small builder object (fb = FatbinBundler(...); fb.add(...); fb.finalize()),
only if Option A's argument shape gets unwieldy — cuda.core uses the builder pattern sparingly
(CUDA graph construction is the only case today).

Option C — Program-level sugar that compiles for multiple archs and bundles the results
(e.g. Program.compile("fatbin", archs=[...])) — likely a follow-up on top of A/B rather than
initial scope, since it multiplies compilation work behind one call.

Open questions for the meeting:

1. Can kind/arch be inferred when the input is an ObjectCode (PTX carries its arch in
   text; cubin would need parsing or an explicit argument)?
2. Options surface: a FatbinOptions dataclass mirroring ProgramOptions/LinkerOptions
   style, vs. plain kwargs?
3. Handle lifetime: route through the _cpp resource-handle registry like other native handles?
4. Version gating & diagnostics for older libnvfatbin (no add_tile_ir/add_index), per #337.
5. Is Option C in scope at all initially?

References

• nvFatbin docs: https://docs.nvidia.com/cuda/nvfatbin/index.html
• Found during the CUDA 12.8 → 13.3 bindings vs. cuda.core gap sweep (2026-07-14)

-- Leo's bot