feat: package llama.cpp b10069 as a C++23 module

[wellwei]

Summary

• Package the official llama.cpp b10069 checkpoint as the C++23 module import llamacpp;.
• Vendor the verified upstream source and generate an audited public C API surface, including typed replacements for stable public value macros.
• Build the CPU backend on Linux x86_64, Linux ARM64, Windows x86_64, and macOS ARM64, with optional Metal support on macOS ARM64.
• Add deterministic import, API/source drift checks, real inference tests, release gates, usage documentation, and a curated upstream update policy.

Consumer Usage

After 0.1.0 is released and published by a separate mcpp-index PR:

mcpp add mcpplibs:llamacpp@0.1.0

Equivalent CPU dependency:

[dependencies.mcpplibs]
llamacpp = "0.1.0"

Metal on macOS ARM64:

[dependencies.mcpplibs]
llamacpp = { version = "0.1.0", features = ["backend-metal"] }

Minimal consumer:

import std;
import llamacpp;

int main() {
    llama_backend_init();
    auto params = llama_model_default_params();
    params.n_gpu_layers = 0;
    llama_model * model = llama_model_load_from_file("model.gguf", params);
    if (!model) {
        llama_backend_free();
        return 1;
    }
    llama_model_free(model);
    llama_backend_free();
}

This is a source package. mcpp resolves the index entry, downloads and verifies the immutable tag archive, extracts it into the package cache, and builds it for the consumer target. Users do not manually unpack the release archive. GGUF model files are not included.

Supported Boundary

Platform	Backend and required evidence
Linux x86_64	CPU build and real GGUF inference
Linux ARM64	Released ARM64 mcpp, static musl helper/consumer, ARM source selection, real GGUF inference
Windows x86_64	CPU build and real GGUF inference
macOS ARM64	CPU build and real GGUF inference
macOS ARM64 with backend-metal	Metal registration, embedded shader use, graph execution, positive layer offload, positive Metal model/compute buffers, decode, and sample

0.1.0 does not include mtmd, CUDA, Vulkan, RPC, C++17 consumer compatibility, or a claim that every upstream model architecture has been tested. Deprecated upstream C APIs remain exported and may emit upstream deprecation warnings when used.

Local Validation

• 112 Python unit tests pass.
• Deterministic upstream import, generated exports, API snapshot, and release mapping checks pass.
• The pinned Stories 15M GGUF passes CPU and Metal load/decode/sample tests.
• Metal evidence on Apple M4 includes 1/7 offloaded layers, a 9.34 MiB MTL0 model buffer, and a 7.88 MiB MTL0 compute buffer.
• Qwen3.5-4B Q4_K_M generated 32 tokens on both CPU and Metal; Metal offloaded 33/33 layers.
• Native Ubuntu 24.04 ARM64 Docker validation passes with static ARM64 helper/consumer binaries, no PT_INTERP, and ARM-only architecture sources.
• All workflows pass pinned actionlint validation.

GitHub Actions on this PR remain authoritative for the complete Linux x86_64, Linux ARM64, Windows x86_64, macOS ARM64, and Metal matrix.

Upstream And Release Policy

• Each llama.cpp-m release maps one wrapper version to one official llama.cpp tag, commit, archive URL, and SHA-256.
• Routine upstream movement is reported weekly but is not mirrored automatically; routine releases are limited to at most monthly.
• Security/correctness, model or quantization support, supported backend improvements, required public API, and platform/toolchain compatibility are explicit update triggers.
• Wrapper-only fixes on the same checkpoint use a patch bump; a new upstream checkpoint or additive API/model/backend support uses a minor bump; intentional public API removal uses a major bump.
• Updates must regenerate and audit exports and snapshots, pass the complete platform/runtime gate, and keep the vendored upstream tree patch-free by default.

This PR does not create a tag, GitHub Release, or mcpp-index entry. After merge, the release tag is created only after the merge commit has a successful complete CI run; mcpp-index publication is a separate cold-consumer PR.