Add selectable Windows CUDA release sidecars

[leehack]

Summary

• add a Windows x64 CUDA sidecar contract and build-hook consumption for native release assets
• default selected CUDA builds to CUDA 13 while allowing llamadart_windows_cuda: 12 or both
• keep CUDA 12 and CUDA 13 dependency families isolated, then select exactly one at runtime from the NVIDIA driver API and the oldest visible GPU capability
• preserve legacy CUDA bundles for the currently pinned b10453 native release
• document the build-time choices and track runtime downloading separately in Support verified on-demand Windows CUDA sidecar downloads at runtime #339

Why

Building CUDA from source dominates the Windows native release. The companion native change in leehack/llamadart-native#37 packages verified upstream CUDA 12.4 and 13.3 artifacts as sidecars bound to the exact native release and ggml-base.dll digest.

This PR is intentionally draft until a sidecar-capable native release exists and the pin can be updated. CUDA remains opt-in through llamadart_native_backends; this does not add a runtime downloader.

Validation

• focused Dart analysis: no issues
• focused hook/runtime suites passed, including corrupt payload, wrong core, unexpected directory, mixed-GPU fallback, and dependency-family isolation regressions
• full VM suite: 1,419 passed, 66 expected skips
• release documentation version verifier passed
• Docusaurus build and link validation passed
• exact-head CI is green for Windows native tests/smoke, macOS native tests, analysis, docs, companion packages, prompt reuse, Web contract, and preview; remaining broad lanes may still be in progress
• root-wide dart analyze remains non-authoritative in this checkout because example packages have unresolved independent dependencies; all touched Dart paths analyze cleanly

Remaining gates

No physical Windows/NVIDIA machine was available. Before enabling or publishing this path, validate on representative CUDA 12- and CUDA 13-capable GPUs, including load/inference and the open MTP acceptance, CUDA lockup, DFlash concurrency, DSpark VRAM-leak, EAGLE, and failed-state-restore reports.

[github-actions]

Chat app preview deployed for 3fe4b88.

• App: https://leehack-llamadart-chat-pr-340.static.hf.space
• Space: https://huggingface.co/spaces/leehack/llamadart-chat-pr-340
• Repo: leehack/llamadart-chat-pr-340

[Copilot]

Pull request overview

Adds support for Windows x64 CUDA “sidecar” release assets, enabling build-time bundling of CUDA 12, CUDA 13 (default), or both, and runtime selection of exactly one compatible CUDA dependency family per process. This fits into the native asset hook + llama.cpp backend loading pipeline by extending the hook to acquire/verify sidecar packs and extending the llama.cpp service to probe the NVIDIA driver/GPU capabilities and preload only matching CUDA dependencies.

Changes:

• Introduces a Windows CUDA sidecar manifest/pack contract with verification, and integrates sidecar acquisition into the native build hook.
• Adds Windows CUDA runtime probing/selection logic and dependency-family isolation in the llama.cpp backend loader.
• Updates docs/changelog and adds targeted unit/integration tests for selection + verification behavior.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
website/docs/platforms/support-matrix.md	Documents Windows CUDA sidecar defaults and llamadart_windows_cuda usage.
website/docs/platforms/native-build-hooks.md	Documents hook behavior for validating/accepting CUDA sidecars.
website/docs/getting-started/installation.md	Adds installation config docs for llamadart_windows_cuda and sidecar behavior.
test/unit/hook/windows_cuda_pack_test.dart	Unit tests for parsing/verifying CUDA pack manifests and payload digests.
test/unit/hook/native_bundle_config_test.dart	Unit tests for parsing/validating llamadart_windows_cuda selection values.
test/unit/hook/build_hook_integration_test.dart	Integration tests asserting legacy CUDA replacement and dual-family bundling behavior.
test/unit/backends/llama_cpp/windows_cuda_selector_test.dart	Unit tests for CUDA sidecar filename parsing and selection policy.
test/unit/backends/llama_cpp/llama_cpp_service_test.dart	Verifies dependency-family isolation for Windows CUDA dependency DLL preloading.
lib/src/hook/windows_cuda_pack.dart	Implements CUDA sidecar release/pack contract parsing and extracted-pack verification.
lib/src/hook/native_bundle_config.dart	Adds llamadart_windows_cuda config parsing and selection enum.
lib/src/backends/llama_cpp/windows_cuda_selector.dart	Implements NVIDIA driver probe + selection logic for CUDA 12 vs 13.
lib/src/backends/llama_cpp/llama_cpp_service.dart	Integrates Windows CUDA major selection and filters dependency preloads by selected family.
hook/build.dart	Acquires/verifies CUDA sidecars and swaps legacy CUDA libs for sidecar content during bundling.
CHANGELOG.md	Records the new Windows CUDA sidecar selection behavior under Unreleased.
AGENTS.md	Adds repo-level rule guidance for allowed llamadart_windows_cuda values and runtime loading constraints.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.

Suppressed comments (3)

test/unit/hook/build_hook_integration_test.dart:850

• The new build-hook behavior includes archive SHA-256 verification, (re)download, and extraction flows, but these fixtures only populate an extracted/ directory and never exercise the “archive missing / checksum mismatch / extraction then verify” paths. Add an integration test that forces _acquireWindowsCudaSidecars down the archive path (e.g., no extracted dir, provide an on-disk tar.gz fixture with wrong digest first, then correct digest) so checksum failure and refresh behavior is covered.

Future<void> _writeCudaSidecarFixtures({
  required Directory cacheDirectory,
  required File coreLibrary,
  required String nativeTag,
  required List<int> majors,
}) async {
  await cacheDirectory.create(recursive: true);
  final artifacts = <Map<String, Object?>>[];
  final coreDigest = sha256.convert(await coreLibrary.readAsBytes()).toString();
  for (final major in majors) {
    final archiveName =
        'llamadart-native-windows-x64-cuda$major-$nativeTag.tar.gz';
    artifacts.add({'file': archiveName, 'sha256': 'a' * 64});
    final extracted = Directory(
      path.join(cacheDirectory.path, 'cuda$major', 'extracted'),
    );
    await extracted.create(recursive: true);

hook/build.dart:1455

• When llamadart_native_path is set, missing sidecar assets immediately throw, which prevents a common workflow of “use a local core bundle, but download official sidecars.” If that workflow should be supported, return null when candidates are not found (so the hook falls back to cache/download) and only throw when the user explicitly points at a sidecar-only override location. If the strict behavior is intentional, it should be explicitly documented in the user-facing installation docs for llamadart_native_path + llamadart_windows_cuda.

File? _resolveLocalWindowsCudaAsset({
  required _NativeBundleConfig nativeConfig,
  required String assetName,
}) {
  final localPath = nativeConfig.localPath;
  if (localPath == null) {
    return null;
  }
  final localFilePath = localPath.toFilePath();
  final root = File(localFilePath).existsSync()
      ? File(localFilePath).parent.path
      : localFilePath;
  final candidates = <String>[
    path.join(root, assetName),
    path.join(root, nativeConfig.tag, assetName),
    path.join(root, nativeConfig.tag, 'windows-x64', assetName),
    path.join(root, 'windows-x64', assetName),
  ];
  for (final candidate in candidates) {
    final file = File(candidate);
    if (file.existsSync()) {
      return file;
    }
  }
  throw Exception(
    'Local native source $root is missing required CUDA sidecar asset '
    '$assetName.',
  );
}

website/docs/getting-started/installation.md:136

• The sentence is broken across lines mid-phrase (“used as a / proxy”), which hurts readability and can render awkwardly depending on markdown formatting rules. Combine this into one continuous sentence (“…is not used as a proxy…”) so it reads cleanly in all renderers.

capability 5.0+. This is runtime selection, so the build machine's GPU is not
used as a
proxy for the target computer. Expect `both` to add roughly 1.1 GB of compressed

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated no new comments.

Suppressed comments (2)

lib/src/hook/windows_cuda_pack.dart:186

• Per-file SHA-256 validation is also case-sensitive. If the sidecar manifest uses uppercase hex, verification will fail even if the payload is correct. Normalize digests to lowercase before validating and storing them.

    final digest = entry['sha256']! as String;
    final size = entry['size']! as int;
    if (!expectedNames.contains(name) ||
        !RegExp(r'^[0-9a-f]{64}$').hasMatch(digest) ||
        size < 0 ||

lib/src/hook/windows_cuda_pack.dart:52

• SHA-256 validation is case-sensitive here (only [0-9a-f]), so a manifest containing uppercase hex will be rejected even though it’s a valid digest. Normalize to lowercase before validating/storing so comparisons against computed digests (which are lowercase) work reliably.

This issue also appears on line 182 of the same file.

      final file = entry['file'];
      final sha256 = entry['sha256'];
      if (file is! String ||
          sha256 is! String ||
          !RegExp(r'^[0-9a-f]{64}$').hasMatch(sha256)) {