neuron-tai/packages/node/native/llama/PATCH-STACK.md

Meshnet llama.cpp patch stack

This directory is the only project-owned fork boundary for llama.cpp. It is locked to e920c523e3b8a0163fe498af5bf90df35ff51d25; changing the pin requires updating the recorded tree/blob assumptions and reviewing every patch anew.

Ordered series

One numbered patch per concern (ADR-0024 local seams only):

1. 0001-cmake-reserve-meshnet-patch-stack-abi-marker.patch adds only an interface-library marker used to prove the patched source was configured. It has no execution, transport, model-loading, or semantic effect.
2. 0002-dense-llama-owned-range-loading.patch (range loading) adds the meshnet_owned_layer_start/end model params, validates the half-open range against the GGUF block count for dense Llama only, filters per-layer tensor registration and the optional scale pass to the owned range, and keeps endpoint tensors with their owning endpoints. Zero/zero params preserve stock whole-model loading.
3. 0003-owned-range-filtered-state-report.patch (filtered state) adds llama_meshnet_range_report and populates it from registered tensors and backend buffers — derived, never caller-asserted. Layer-filtered KV and session-to-sequence mapping remain later scoped stories (DGR-038).
4. 0004-dense-boundary-io-endpoint-guard.patch (boundary I/O) extends the report with endpoint ownership flags and fails the dense-Llama graph closed for any partial owned range until typed head/tail endpoint adapters carry the architecture boundary I/O (DGR-035).
5. 0005-worker-range-report-hook.patch (worker hooks) exposes the llama_model_meshnet_range_report C API the project-owned worker binds to and registers a model-free native fixture test for it.
6. 0006-meshnet-range-report-tool.patch (range reporting) adds the project-owned meshnet-range-report tool: it loads one GGUF artifact through the owned-range loader and prints a JSON document derived from the loaded model state — the owned-range report, the registered tensor set audited against the requested ownership, and backend-buffer byte counts. It never builds or runs a compute graph.

Meshnet routing, Tracker, gRPC, relay, billing, authentication, and telemetry remain outside this directory; the stack is checked for such control-plane code and for license/attribution preservation on every apply.

Upstream assumptions and fail-closed verification

patches/UPSTREAM-ASSUMPTIONS.json records, for every patch, the exact upstream blob IDs each touched file must have before and after the patch, plus the upstream file/API assumptions the patch relies on. scripts/llama_cpp_dependency.py verify runs the deterministic cycle against the exact manifest pin:

1. Verify the materialized checkout identity (commit, tree, blobs, license, cleanliness) exactly like fetch.
2. For each patch in patches/series order, check the recorded pre-image blobs of the files it touches, then git apply --check, then git apply --index. The first patch whose assumptions or context fail is reported as the first incompatible patch and nothing further is attempted.
3. Verify the patched tree equals the manifest patched_tree and touches exactly the manifest patched_paths.
4. Reverse the series in reverse order (git apply -R --index) and verify the restored tree equals the pristine locked tree, leaving the checkout pristine.

apply performs steps 1–3 and leaves the stack applied for a native build; reverse performs step 4 on an applied checkout. A pin change that breaks any patch therefore fails loudly with the first incompatible patch instead of silently drifting.

scripts/llama_cpp_dependency.py fetch reads the in-repo manifest and checks out only its exact commit as detached HEAD in build/llama.cpp/source, an ignored build workspace. It verifies the exact commit/tree and baseline blobs before use. A later offline fetch may reuse that cache only after the same clean identity verification; an attached branch, tag/repository override, arbitrary destination, symlinked workspace, dirty checkout, ignored injected file, or tracked-file modification hidden by Git index flags is refused. The tool validates every patch digest and context with git apply --check, then applies the series in patches/series order. Tracked executable modes are checked physically when Git reports core.filemode=true; on mounted filesystems without POSIX mode fidelity, the locked index tree remains the canonical mode record while every working-file blob is independently re-hashed.

Current semantic boundary

The stock pinned build is infrastructure evidence only. Per DGR-017, GLM-5.2 can use a dense-MLA compatibility fallback at this point; a successful build or llama-cli --version does not show native DSA/IndexShare, GLM semantic acceptance, numerical parity, performance, or route certification. DGR-018 and DGR-019 own those checks. Dense Llama remains only a later structural fixture.