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

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

**Status:** implementation complete; independently re-verified in a fresh Ralph session (2026-07-22) against live source and the real cached upstream checkout, per `RALPH-CONTEXT.md`'s "inspect live source/tests rather than trusting legacy pass states" mandate. `prd.json`'s `DGR-028.passes` is now `true`.
**Authority:** local `prd.json` is authoritative; live Gitea #12 is a 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.

## Independent re-verification (2026-07-22, fresh Ralph session)

The prior evidence above was carried over from an earlier session that recorded
a focused native CMake/CTest build (`test-meshnet-range-ownership`) it could
not independently reverify because `build/` was not present at commit time
(see the DGR-028 commit message, `7da90ef`). This session re-ran the
Python/Git-level contract live and end to end, and is explicit about what
could and could not be re-checked:

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

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

python3 scripts/llama_cpp_dependency.py verify --workspace build/llama.cpp
# reused verified offline cache; apply -> assumption/boundary checks ->
# reverse succeeded; source left at pristine detached HEAD

python3 scripts/llama_cpp_dependency.py apply --source-dir build/llama.cpp/source
# git -C build/llama.cpp/source diff --cached --name-only ==
#   CMakeLists.txt, cmake/meshnet-patch-stack.cmake, include/llama.h,
#   src/llama-model.cpp, src/llama-model.h, src/models/llama.cpp,
#   tests/CMakeLists.txt, tests/test-meshnet-range-ownership.cpp
# git -C build/llama.cpp/source write-tree ==
#   c0045714735ae5ee7b7334a480d8ac04e03e1b18 (matches UPSTREAM_LOCK.json patched_tree)

python3 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)
# git -C build/llama.cpp/source rev-parse HEAD HEAD^{tree}
#   -> e920c523e3b8a0163fe498af5bf90df35ff51d25 / 6c91a11407a3a3fb160f5dac705f9c59718f54f1

python3 -m pytest -q tests/test_llama_cpp_dependency.py tests/test_ralph_prd_schema.py
# 115 passed

python3 -m compileall -q packages tests
# exit 0

git diff --check
# exit 0
```

`cmake` is not installed in this environment (`which cmake` fails), so the
native CMake/CTest build claim from the prior session (`test-meshnet-range-ownership`
1/1 Passed) could **not** be independently re-executed here; it is neither
re-confirmed nor retracted, just carried forward from `7da90ef` without a new
build-verified claim in this session. Everything at the Python/Git contract
level — patch digests, assumption-blob enforcement, apply/reverse against the
real cached upstream checkout, patched-tree identity, and pristine-restore —
was independently re-verified against live source in this fresh session.

## prd.json repair (unrelated to DGR-028 itself)

Before editing `DGR-028.passes`, `prd.json` was found with its top-level
`sourceOfTruth`/`qualityGates`/`metadataSchema`/`milestones`/`supersededStories`
fields silently dropped again (`branchName` was also missing but had already
been restored by a prior in-flight edit) — the same ralph-tui round-trip bug
documented for DGR-019/DGR-020. Unlike those occurrences, `userStories` in the
working tree was *not* unchanged: it already carried legitimate uncommitted
`passes: true`/`completionNotes` updates for DGR-019, DGR-020, DGR-024, and
DGR-026 from other stories' sessions. The missing top-level sections were
restored from `git show HEAD:.scratch/distributed-gguf-runtime/prd.json`
while preserving the current `userStories` array verbatim, then
`DGR-028.passes` was set `true` with `completionNotes` added, and
`.scratch/distributed-gguf-runtime/issues/028-implement-numbered-patch-stack-apply-and-verification.md`
was regenerated via `scripts/ralph_prd_schema.py render` (which only prints;
the caller must redirect it into the issue file — it does not write in
place). `python3 scripts/ralph_prd_schema.py validate` and
`python3 -m pytest -q tests/test_ralph_prd_schema.py` (108 passed) both pass
against the repaired file.