neuron-tai/.scratch/distributed-gguf-runtime/evidence/DGR-028/README.md

# DGR-028 evidence — numbered llama.cpp patch-stack verification

**Status:** implementation complete; every gate below was re-executed in the continuation session (2026-07-18, detached provider worktree). Final independent P0/P1 controller review is pending.  
**Authority:** live Gitea #12; local PRD is a secondary projection.  
**Upstream pin:** `e920c523e3b8a0163fe498af5bf90df35ff51d25` (`llama.cpp`)

## Implemented

- Replaced the stale non-applying range-loader patch with an ordered five-patch stack whose concerns are separated into build marker, dense-Llama owned-range loading, filtered state reporting, boundary I/O fail-closed guard, and worker range-report hook plus native fixture.
- Added `patches/UPSTREAM-ASSUMPTIONS.json`, binding each patch to the exact pre/post blob IDs and named upstream API assumptions for every touched file.
- Extended `scripts/llama_cpp_dependency.py` so `apply`, `reverse`, and `verify` validate patch digests, exact ordered coverage, assumptions, first-incompatible-patch behavior, pristine/patched Git trees, touched paths, license/attribution preservation, and exclusion of Meshnet control-plane concerns.
- `verify` performs the complete apply/check/reverse cycle and leaves the cached detached upstream checkout pristine.
- Updated the lock's exact patched tree and patch checksums. No model artifact was downloaded or created.

## Controller repairs during verification

The preserved Kimi output was not accepted from prose. Initial controller execution found and repaired:

1. a missing `_git` helper that made the dependency verifier raise `NameError`;
2. assumptions resolved relative to the repository root rather than the llama manifest directory;
3. the documented `verify`/`reverse` contract was not wired into the CLI or apply path;
4. assumptions and control-plane/license boundaries were defined but never enforced during apply;
5. a stale Python test hardcoded the old two-patch count;
6. the native fixture made an invalid strict resident-buffer-size comparison. Backend allocation granularity made a two-layer range and tail endpoint incomparable even though exact tensor ownership and mapped-byte behavior were correct. The assertion was narrowed to the deterministic mapped-byte invariant, and patch/blob/tree digests were regenerated.

## Verification

All commands below were re-executed in the continuation session on the exact
pin; results are from that run.

```text
cd packages/node/native/llama/patches && sha256sum -c SHA256SUMS
# all five patches OK

python scripts/llama_cpp_dependency.py inspect
# exact commit/tree, MIT license, five-patch series, no model downloads

python scripts/llama_cpp_dependency.py verify --workspace build/llama.cpp
# reused verified offline cache; apply/check/reverse succeeded; source returned to clean detached HEAD

git -C build/llama.cpp/source status --short --branch --untracked-files=all
# ## HEAD (no branch)

python -m pytest -q tests/test_llama_cpp_dependency.py
# 7 passed in 0.27s

python -m compileall -q scripts/llama_cpp_dependency.py tests/test_llama_cpp_dependency.py
# exit 0
python -m compileall -q packages tests
# exit 0

git diff --check
# exit 0
```

Focused native gate against the patched exact pin (apply first because `verify`
intentionally restores the source checkout to pristine state, then reverse after
the test):

```text
python scripts/llama_cpp_dependency.py apply --source-dir build/llama.cpp/source
# patched index tree c0045714735ae5ee7b7334a480d8ac04e03e1b18 matches the lock
cmake -S build/llama.cpp/source -B build/llama.cpp/dgr028-build-verify \
  -G 'Unix Makefiles' -DCMAKE_BUILD_TYPE=Release -DLLAMA_BUILD_TESTS=ON \
  -DLLAMA_BUILD_EXAMPLES=OFF -DLLAMA_BUILD_SERVER=OFF \
  -DLLAMA_BUILD_TOOLS=OFF -DLLAMA_BUILD_APP=OFF -DLLAMA_CURL=OFF
cmake --build build/llama.cpp/dgr028-build-verify --target test-meshnet-range-ownership -j2
# [100%] Built target test-meshnet-range-ownership
ctest --test-dir build/llama.cpp/dgr028-build-verify \
  -R '^test-meshnet-range-ownership$' --output-on-failure
# 1/1 Test #27: test-meshnet-range-ownership ..... Passed 0.01 sec
python scripts/llama_cpp_dependency.py reverse --source-dir build/llama.cpp/source
git -C build/llama.cpp/source status --short --branch --untracked-files=all
# ## HEAD (no branch); HEAD e920c523e3b8a0163fe498af5bf90df35ff51d25, tree 6c91a11407a3a3fb160f5dac705f9c59718f54f1
```

Build-directory note: `build/llama.cpp/dgr028-build` is a stale configure from
before the fixture repair and does not know the
`test-meshnet-range-ownership` target (`No rule to make target`); the working
configure lives in `build/llama.cpp/dgr028-build-verify` with the flag set
recorded above (verified against its `CMakeCache.txt`). Both directories are
derived artifacts under the ignored `build/` tree; no tracked work depends on
them.

A broad `cmake --build ... --target test` was also attempted after building only the focused target. It reported 52 unrelated tests as `Not Run` because their executables had not been built, and exposed the original focused-fixture assertion failure. It is not presented as a full-suite gate. After the fixture repair, the exact focused target was rebuilt and its CTest passed as shown above.

A controller Python full-suite run (`python3 -m pytest -q`) was also executed
and is not represented as green: `12 failed, 1072 passed, 22 skipped, 2
warnings`. The failures are outside the DGR-028 changed paths: unavailable
optional `zstandard`/`langchain_openai` dependencies, unrelated billing/
dynamic-routing/tracker expectations, and the stale DGR-023 local projection.
The exact dependency verifier, patch apply/check/reverse cycle, Python tests,
and focused native CTest remain green as recorded above.

## Changed files

- `packages/node/native/llama/PATCH-STACK.md`
- `packages/node/native/llama/THIRD_PARTY_NOTICES.md`
- `packages/node/native/llama/UPSTREAM_LOCK.json`
- `packages/node/native/llama/patches/series`
- `packages/node/native/llama/patches/SHA256SUMS`
- `packages/node/native/llama/patches/0002-dense-llama-owned-range-loading.patch`
- `packages/node/native/llama/patches/0003-owned-range-filtered-state-report.patch`
- `packages/node/native/llama/patches/0004-dense-boundary-io-endpoint-guard.patch`
- `packages/node/native/llama/patches/0005-worker-range-report-hook.patch`
- `packages/node/native/llama/patches/UPSTREAM-ASSUMPTIONS.json`
- `scripts/llama_cpp_dependency.py`
- `tests/test_llama_cpp_dependency.py`
- `.scratch/distributed-gguf-runtime/evidence/DGR-028/README.md`

The superseded `0002-dense-llama-owned-range-loader.patch` is removed.

## Limitations and handoff

- This is patch-stack and model-free native fixture evidence, not real-model correctness, memory-fit, performance, or route certification.
- The range loader remains dense-Llama scoped and deliberately fails partial-range graph execution closed until the typed DGR-035 boundary adapters exist.
- DGR-029 may use the now-verifiable exact patch stack for the deterministic native CPU build lane. DGR-034 owns real dense-Llama range behavior and memory evidence.