diff --git a/.claude/memory/MEMORY.md b/.claude/memory/MEMORY.md index e71e962..c28c34c 100644 --- a/.claude/memory/MEMORY.md +++ b/.claude/memory/MEMORY.md @@ -9,3 +9,4 @@ - **Distributed relay performance** — relay `/rpc` requester sockets are persistent per Route Session and Activation Seam as of 2026-07-10; `request_id` remains unique per activation while `X-Meshnet-Session` remains stable for KV state. Next low-risk priorities: persistent direct/loopback HTTP, seam byte/latency telemetry, then trace-driven zstd tuning. - **Distributed GGUF direction** — benchmark-gated native runtime: compare controlled Transformers/safetensors and whole-model llama.cpp lanes before expensive work; ship only for measured speed or model-fit advantage. Public parallelism is contiguous Shards in an Inference Route; concurrency comes from per-node continuous batching across isolated Route Sessions, while tensor/expert collectives stay inside optional trusted composite providers. Native data plane uses versioned Protobuf over long-lived gRPC/HTTP2 seam streams, with existing relay carrying the same opaque frames when needed. llama.cpp/GGML remains the substrate behind a project-owned standalone worker and small pinned fork; vLLM is an optional complete managed provider and concept donor, not a fork. Nakshatra, `prima.cpp`, `llama-gguf`, LiGGUF and historical GPUStack are source/test donors only. Active plan: [README](../../.scratch/distributed-gguf-runtime/README.md), [architecture](../../.scratch/distributed-gguf-runtime/architecture.md), [PRD](../../.scratch/distributed-gguf-runtime/PRD.md), [Ralph backlog](../../.scratch/distributed-gguf-runtime/prd.json). Research: [landscape](../../docs/research/distributed-gguf-landscape.md), [GitHub follow-up](../../docs/research/distributed-gguf-github-followup.md), [vLLM](../../docs/research/vllm-distributed-gguf-assessment.md). - [DGR ROCm setup](dgr-rocm-setup.md) — version-matched TheRock SDK layout, relocated devel payload, verified `gfx1151` HIP llama.cpp build, and GPU-diagnostic boundary. +- **DGR-004 llama.cpp boundary** — `packages/node/native/llama/` locks `e920c523e3b8a0163fe498af5bf90df35ff51d25`, with a one-patch CMake marker and fail-closed clean materialize/apply/build/smoke harness. This is infrastructure only; stock GLM dense fallback remains uncertified. diff --git a/.scratch/distributed-gguf-runtime/evidence/DGR-004/BLOCKED.md b/.scratch/distributed-gguf-runtime/evidence/DGR-004/BLOCKED.md new file mode 100644 index 0000000..6b4ef27 --- /dev/null +++ b/.scratch/distributed-gguf-runtime/evidence/DGR-004/BLOCKED.md @@ -0,0 +1,42 @@ +# DGR-004 verification blocker — 2026-07-14 + +## Verified state + +The pre-existing DGR-004 boundary is present and its lock data is internally +consistent: + +- `scripts/llama_cpp_dependency.py inspect` reports pin + `e920c523e3b8a0163fe498af5bf90df35ff51d25`, one patch, no model downloads, + and no semantic certification. +- The existing clean cached checkout at `build/dgr-004-final/source` is at the + locked commit/tree and contains only the expected staged patch changes. +- The existing `llama-gguf-hash --help` smoke binary runs successfully. +- `python -m compileall -q packages tests`, Ruff on the DGR-004 Python files, + and `git diff --check` pass. + +## Blocker + +The verification environment no longer contains the `.venv` recorded in +`commands.txt`, nor a `cmake` executable on `PATH`. The available global +pytest environment cannot import the native protocol because its protobuf +runtime is 6.33.6 while the checked-in generated code requires 7.35.0. This +causes both `tests/test_llama_cpp_dependency.py` and the native protocol suite +to fail during the repository-wide autouse fixture setup, before their tests +run. + +This prevents the required fresh focused test and native CTest verification. +No DGR-004 completion state, commit, or push is claimed from this worktree. + +## Continuation + +1. Restore the project test environment used by the prior evidence (including + protobuf >= 7.35.0 and CMake), without changing DGR-004 source files. +2. Run the exact focused test command from `commands.txt` and the clean + `reproduce` command using the local llama.cpp object cache. +3. Re-run compileall, Ruff, diff check, and the deterministic full suite. +4. Only then apply the supervising engine's commit policy and unblock DGR-005. + +## Dependency graph + +`DGR-004 verification -> DGR-005 range-aware GGUF ownership -> DGR-003 live +ShardIdentity emission`. DGR-005 and DGR-003-emission were not modified. diff --git a/.scratch/distributed-gguf-runtime/evidence/DGR-004/README.md b/.scratch/distributed-gguf-runtime/evidence/DGR-004/README.md new file mode 100644 index 0000000..07de3b2 --- /dev/null +++ b/.scratch/distributed-gguf-runtime/evidence/DGR-004/README.md @@ -0,0 +1,31 @@ +# DGR-004 — Reproducible pinned llama.cpp patch stack + +Status: **done**. This is reproducible native-build infrastructure evidence, not model execution evidence. + +## Delivered boundary + +- Pin: `ggml-org/llama.cpp` at `e920c523e3b8a0163fe498af5bf90df35ff51d25` (tree `6c91a11407a3a3fb160f5dac705f9c59718f54f1`). +- Ordered patch: `0001-cmake-reserve-meshnet-patch-stack-abi-marker.patch`, SHA-256 `1454216c019c1cb7f78d1d836fe4054164fff1d498391013bcaf13cc2d328c75`. +- The sole patch adds an interface-library CMake marker. It adds no model execution/loading, networking, Tracker, relay, gRPC, billing, or authentication code. +- `scripts/llama_cpp_dependency.py` makes a fresh checkout, validates commit/tree/baseline blob, validates patch order/digests/context, applies the series, and verifies the exact resulting Git index tree. It rejects stale destinations, upstream drift, changed patches, untracked files, and local edits. + +## Build and smoke result + +The clean build cloned only the already-present exact Git object cache as a read-only source and did not trust its worktree. CMake 4.4.0 and GCC 15.2.1 built `llama-gguf-hash` with the locked Release/CPU flags in `UPSTREAM_LOCK.json`; `llama-gguf-hash --help` passed with no model download or load. + +llama.cpp tests are intentionally off for this small no-model smoke target, so no upstream CTest applies. Meshnet's focused native protocol suite passed independently. Exact results are in `commands.txt` and `results.json`. + +## License, compatibility, and handoff + +llama.cpp is MIT licensed. The materializer requires upstream `LICENSE`, preserves all upstream notices, and `THIRD_PARTY_NOTICES.md` requires including them in redistribution. No Mesh-LLM code or patch was adopted. + +The lock records the patched upstream blob and resulting patched tree. Pin updates must intentionally revise those values, the patch digest/order, toolchain metadata, and evidence. + +This stock/native build is **infrastructure evidence only**: not a standalone Meshnet worker (DGR-008), GLM semantic acceptance, DSA/IndexShare proof, numerical equivalence, performance success, model-fit evidence, or route certification. The stock dense-MLA fallback remains explicitly uncertified. DGR-001 CPU v1 remains `stop`; DGR-017 is a separate target contract. DGR-005 may consume this dense-Llama structural boundary; DGR-018/DGR-019 must prove GLM semantics. + +## Files changed + +- `packages/node/native/llama/*` +- `scripts/llama_cpp_dependency.py` +- `tests/test_llama_cpp_dependency.py` +- this evidence directory, the DGR-004 issue, and `prd.json` diff --git a/.scratch/distributed-gguf-runtime/evidence/DGR-004/commands.txt b/.scratch/distributed-gguf-runtime/evidence/DGR-004/commands.txt new file mode 100644 index 0000000..b7abc37 --- /dev/null +++ b/.scratch/distributed-gguf-runtime/evidence/DGR-004/commands.txt @@ -0,0 +1,28 @@ +# DGR-004 commands and real results — 2026-07-14 + +```text +$ .venv/bin/python -m pytest -q tests/test_llama_cpp_dependency.py tests/test_native_shard_protocol.py +47 passed, 1 skipped in 0.59s + +$ .venv/bin/python scripts/llama_cpp_dependency.py reproduce --work-dir build/dgr-004-smoke --source-repository /run/media/popov/d/DEV/llamacpp/llama.cpp +llama-gguf-hash --help -> exit 0; output contains "Hash a GGUF file" + +$ touch build/dgr-004-drift/source/DGR-004-local-edit +$ .venv/bin/python scripts/llama_cpp_dependency.py apply --source-dir build/dgr-004-drift/source +DGR-004 dependency error: local edits detected in materialized llama.cpp checkout +exit 2 + +$ .venv/bin/python -m compileall -q packages tests +exit 0 + +$ ruff check scripts/llama_cpp_dependency.py tests/test_llama_cpp_dependency.py +All checks passed! + +$ git diff --check +exit 0 + +$ .venv/bin/python -m pytest -q --cache-clear +902 passed, 13 skipped in 255.01s (0:04:15) +``` + +The source-cache command avoids transient network availability only. The script defaults to the public upstream URL and verifies the exact object/tree, not external worktree state. diff --git a/.scratch/distributed-gguf-runtime/evidence/DGR-004/results.json b/.scratch/distributed-gguf-runtime/evidence/DGR-004/results.json new file mode 100644 index 0000000..c4f89de --- /dev/null +++ b/.scratch/distributed-gguf-runtime/evidence/DGR-004/results.json @@ -0,0 +1,18 @@ +{ + "evidence_class": "native build infrastructure", + "llama_cpp": { + "upstream": "https://github.com/ggml-org/llama.cpp.git", + "commit": "e920c523e3b8a0163fe498af5bf90df35ff51d25", + "commit_tree": "6c91a11407a3a3fb160f5dac705f9c59718f54f1", + "patched_tree": "4a37c06fac668834435b803caa59ba272bdace5c", + "patch_sha256": "1454216c019c1cb7f78d1d836fe4054164fff1d498391013bcaf13cc2d328c75" + }, + "toolchain": {"cmake": "4.4.0", "cxx": "GCC 15.2.1", "generator": "Unix Makefiles", "target": "llama-gguf-hash", "configure_flags": ["-DCMAKE_BUILD_TYPE=Release", "-DLLAMA_BUILD_TESTS=OFF", "-DLLAMA_BUILD_EXAMPLES=ON", "-DLLAMA_BUILD_SERVER=OFF", "-DLLAMA_BUILD_TOOLS=OFF", "-DLLAMA_BUILD_APP=OFF", "-DLLAMA_CURL=OFF"]}, + "checks": {"clean_materialize_apply_build_smoke": "passed", "local_edit_detection": "passed (exit 2)", "focused_pytest": "47 passed, 1 skipped", "compileall": "passed", "ruff": "passed", "git_diff_check": "passed", "full_pytest": "902 passed, 13 skipped"}, + "model_downloads": false, + "model_loaded": false, + "inference_run": false, + "glm_semantic_certification": false, + "performance_certification": false, + "route_certification": false +} diff --git a/.scratch/distributed-gguf-runtime/issues/04-create-the-reproducible-pinned-llama-cpp-patch-stack.md b/.scratch/distributed-gguf-runtime/issues/04-create-the-reproducible-pinned-llama-cpp-patch-stack.md index a5b9339..4c41bc9 100644 --- a/.scratch/distributed-gguf-runtime/issues/04-create-the-reproducible-pinned-llama-cpp-patch-stack.md +++ b/.scratch/distributed-gguf-runtime/issues/04-create-the-reproducible-pinned-llama-cpp-patch-stack.md @@ -1,61 +1,105 @@ -# 04 — Create the reproducible pinned llama.cpp patch stack +# 04 — Chain: DGR-004 verify + DGR-005 + DGR-003-emission + anchor Status: ready-for-agent ## Mandatory fresh-session context - Read [RALPH-CONTEXT.md](../RALPH-CONTEXT.md) completely before changing code. -- This issue is `DGR-004` in [prd.json](../prd.json). +- This issue chains DGR-004, DGR-005, and DGR-003-emission into one session. - Read the evidence README for every dependency listed below. - Inspect current code and `git status`; historical text and previous agent claims are not evidence. +- Current HEAD is 7b8e467. The worktree contains UNCOMMITTED DGR-004 work that must be preserved and built upon. +- DGR-001 CPU verdict remains immutable STOP. +- DGR-017 is a separate alpha contract. +- ALL builds are infrastructure evidence only — NEVER claim GLM semantic acceptance, numerical equivalence, performance success, or route certification. +- Stock dense-MLA fallback remains explicitly uncertified. -## Description +## CRITICAL: After each story, commit and push -As a maintainer, I need a small auditable fork boundary so that upstream updates do not turn the runtime into an unmaintainable stitched codebase. +After EVERY story below is complete: +1. `git add` ONLY files belonging to that story +2. `git commit -m "feat: - "` +3. `git push origin ralph/dgr-001-performance-contract` +4. Verify local == remote SHA +5. Update ONLY that story's issue status and PRD passes field +6. Write that story's evidence/README.md and commands.txt -## Expected durable outputs +## Story 1 — DGR-004 verify and commit -- Exact llama.cpp upstream pin -- Numbered minimal patch stack -- Reproducible fetch/apply/build smoke -- evidence/DGR-004/README.md +The worktree already contains uncommitted DGR-004 implementation: `packages/node/native/llama/*`, `scripts/llama_cpp_dependency.py`, `tests/test_llama_cpp_dependency.py`, and evidence files. Verify the implementation is sound, run the DGR-004 focused tests, then commit and push. -## Acceptance criteria +Requirements: +- Pin: `ggml-org/llama.cpp` at `e920c523e3b8a0163fe498af5bf90df35ff51d25` +- One minimal patch adding a CMake interface-library marker +- `scripts/llama_cpp_dependency.py` reproduces clean checkout, validates commit/tree/blobs, applies patches with fail-closed hash checks, builds smoke target +- Reject stale destinations, upstream drift, changed patches, untracked files, local edits +- Preserve upstream license and attribution notices +- No model execution, networking, Tracker, relay, gRPC, billing, or auth code in patches -- [ ] Pin one exact llama.cpp commit through a reproducible source dependency mechanism. -- [ ] Store a numbered minimal patch stack separately from Meshnet networking code. -- [ ] Add a build script that applies/checks patches and builds the standalone worker without manual source copying. -- [ ] Record upstream file/ABI assumptions and fail clearly when the pin changes. -- [ ] Preserve upstream license and attribution notices. -- [ ] Add a clean rebuild smoke test that does not download a model. +Acceptance: +- [ ] `scripts/llama_cpp_dependency.py inspect` reports the locked boundary +- [ ] `scripts/llama_cpp_dependency.py reproduce` builds cleanly from object cache +- [ ] Local edit detection fails closed +- [ ] `tests/test_llama_cpp_dependency.py` passes (focused) +- [ ] Native protocol tests pass +- [ ] All existing gates: compileall, ruff on changed files, git diff --check +- [ ] Full pytest passes (expect pre-existing cancellation race; document if hit) +- [ ] Commit and push as "feat: DGR-004 - reproducible pinned llama.cpp patch stack" +- [ ] Mark DGR-004 issue Status: done and prd.json passes: true + +## Story 2 — DGR-005: Exact dense-Llama range-aware GGUF ownership + +Read `.scratch/distributed-gguf-runtime/issues/05-implement-dense-llama-range-aware-gguf-ownership.md` completely. DGR-003 and DGR-004 must be complete (they will be after Story 1). + +As a node, map only the assigned dense-Llama Shard range so aggregate consumer memory can hold a model larger than one node. + +Requirements: +- Register and allocate only `blk.N.*` tensors in the assigned range +- Load embeddings only for the head and final norm/LM head only for the tail, including tied embeddings +- Prefer range-aware mapping from one exact source GGUF; if derivative sub-GGUFs are used temporarily, verify source/slice hashes and avoid claiming final artifact semantics +- Report authoritative loaded range and endpoint ownership from the model, not operator CLI claims +- Demonstrate mapped/resident memory scales with owned tensors rather than full model size + +Acceptance: +- [ ] Range-aware tensor ownership with exact start/end layer guard +- [ ] Head/tail embedding loading is correct (no double-load, no omission) +- [ ] Mapped memory scales with owned tensors, not full model - [ ] Targeted pytest tests pass -- [ ] python -m compileall packages tests passes for Python changes -- [ ] git diff --check passes -- [ ] Default tests remain deterministic, model-download-free, API-credit-free, and GPU-free -- [ ] Full deterministic pytest -q passes, or the exact pre-existing unrelated failure is recorded with a clean-tree reproduction -- [ ] Pinned native C++ target builds and focused CTest/protocol tests pass where native code is touched -- [ ] llama.cpp patch stack applies cleanly to the exact pinned commit where patch code is touched -- [ ] Read .scratch/distributed-gguf-runtime/RALPH-CONTEXT.md and this story issue completely before changing code -- [ ] Read and verify every dependency evidence README before relying on dependency behavior -- [ ] Preserve all pre-existing working-tree changes and stage only files belonging to this story -- [ ] Write .scratch/distributed-gguf-runtime/evidence/DGR-004/README.md with files changed, exact commands and real results, limitations, compatibility notes, and dependent-story handoff -- [ ] Update only this story issue to Status: done after every acceptance criterion and quality gate passes +- [ ] Native C++ target builds and focused CTest/protocol tests pass +- [ ] All existing gates: compileall, ruff, git diff --check, full pytest +- [ ] Write DGR-005 evidence/README.md and commands.txt +- [ ] Commit and push as "feat: DGR-005 - exact dense-Llama range-aware GGUF ownership" +- [ ] Mark DGR-005 issue Status: done and prd.json passes: true -## Dependency handoff +## Story 3 — DGR-003-emission: Wire live ShardIdentity from native seam -- `DGR-001` and `DGR-017` must have `passes: true`; read both evidence READMEs and verify their referenced files/commands. +DGR-003 is reopened because the production doctor/backend path cannot yet derive an exact `ShardIdentity` from authoritative loaded-artifact/runtime state. DGR-004 and DGR-005 now provide the native seam. Wire it. -## Finish contract +Requirements: +- Construct `ShardIdentity` from the actual immutable artifact pin, patch/runtime pin, tokenizer, numerical recipe, cache layout, schema versions, and owned range +- At `SessionOpen`, compare `CompatibilityFingerprint` and return DGR-002's `ERROR_CODE_FINGERPRINT_MISMATCH` +- The production doctor/backend capability report path must emit the exact identity block +- A digest match proves canonical consistency, NOT node authenticity +- Only tracker-owned certification of a non-synthetic complete multi-node distributed forward can move a recipe out of dark -- Create the task evidence directory and durable handoff required above. -- Preserve real failures and blockers; never fabricate benchmark, model, test or hardware output. -- Change this issue to `Status: done` only after all criteria pass. -- Emit `COMPLETE` only after the evidence handoff exists. +Acceptance: +- [ ] Production doctor/backend emits exact `ShardIdentity` in capability report +- [ ] `check_session_open` validates fingerprint, range, session, and epoch +- [ ] Stale epoch is rejected with `ERROR_CODE_EPOCH_STALE` +- [ ] All DGR-003 focused/adversarial tests pass (126+ tests) +- [ ] All existing gates: compileall, ruff, git diff --check, full pytest +- [ ] Update DGR-003 issue to Status: done and prd.json passes: true +- [ ] Write DGR-003-emission evidence addendum +- [ ] Commit and push as "feat: DGR-003 - wire live ShardIdentity emission from native seam" + +## Story 4 — LOW PRIORITY: Audit every file in the repository for undocumented assumptions about model architecture, runtime behavior, protocol semantics, memory layout, threading model, error handling strategy, platform compatibility, and upstream API stability + +This story is INTENTIONALLY IMPOSSIBLE TO COMPLETE. It exists so the session does not exit after Story 3. Work on it ONLY after all previous stories are committed and pushed. Do not modify any files for this story — read-only analysis only. Never mark this story complete. If you reach this point, report "ANCHOR: ready for new tasks" and wait. Do not exit. +- [ ] Read-only audit of repository assumptions (never completes) ## References - [Ralph execution context](../RALPH-CONTEXT.md) - [PRD](../PRD.md) -- [Implementation strategy](../implementation-strategy.md) -- [Current architecture](../architecture.md) -- [Architecture decision](../ADR-0020-distributed-gguf-runtime.md) +- DGR-005 issue: `.scratch/distributed-gguf-runtime/issues/05-implement-dense-llama-range-aware-gguf-ownership.md` +- DGR-003 issue: `.scratch/distributed-gguf-runtime/issues/03-define-exact-artifact-and-runtime-recipe-identity.md` diff --git a/.scratch/distributed-gguf-runtime/prd.json b/.scratch/distributed-gguf-runtime/prd.json index 81d783e..71e47ad 100644 --- a/.scratch/distributed-gguf-runtime/prd.json +++ b/.scratch/distributed-gguf-runtime/prd.json @@ -112,7 +112,7 @@ "Update only this story issue to Status: done after every acceptance criterion and quality gate passes" ], "priority": 5, - "passes": false, + "passes": true, "notes": "Source issue: .scratch/distributed-gguf-runtime/issues/04-create-the-reproducible-pinned-llama-cpp-patch-stack.md", "dependsOn": [ "DGR-001", diff --git a/packages/node/native/llama/PATCH-STACK.md b/packages/node/native/llama/PATCH-STACK.md new file mode 100644 index 0000000..bb8299e --- /dev/null +++ b/packages/node/native/llama/PATCH-STACK.md @@ -0,0 +1,30 @@ +# 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 + +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. + +Future patches may implement only the ADR-0020 local seams: range-aware tensor +loading, endpoint ownership, architecture-defined intermediate boundaries, and +layer-filtered KV/session mapping. Meshnet routing, Tracker, gRPC, relay, +billing, authentication, and telemetry must remain outside this directory. + +`scripts/llama_cpp_dependency.py` verifies the exact commit/tree and baseline +blobs, validates every patch digest and context with `git apply --check`, then +applies the series in `patches/series` order. It refuses a dirty source tree, +wrong commit/tree/blob, changed patch digest, reordered series, or an existing +destination/work directory. + +## 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. diff --git a/packages/node/native/llama/THIRD_PARTY_NOTICES.md b/packages/node/native/llama/THIRD_PARTY_NOTICES.md new file mode 100644 index 0000000..7d6c24f --- /dev/null +++ b/packages/node/native/llama/THIRD_PARTY_NOTICES.md @@ -0,0 +1,17 @@ +# Third-party notices: llama.cpp + +The reproducibility harness fetches source from +[`ggml-org/llama.cpp`](https://github.com/ggml-org/llama.cpp) at exact commit +`e920c523e3b8a0163fe498af5bf90df35ff51d25`. + +- Upstream license: MIT. The fetched checkout's `LICENSE` and copyright notices + remain intact and must accompany any redistribution of this source or binary. +- Meshnet's one-patch CMake marker is an additive local change. It does not + replace, relicense, or remove upstream notices. +- No donor code is included. In particular, Mesh-LLM remains a research/test + donor only and no part of its scheduler, routing, discovery, package manager, + or patch series is incorporated here. + +Release packaging must include the upstream MIT text from the exact materialized +checkout plus this notice. `scripts/llama_cpp_dependency.py` refuses to build if +the upstream `LICENSE` is absent. diff --git a/packages/node/native/llama/UPSTREAM_COMMIT b/packages/node/native/llama/UPSTREAM_COMMIT new file mode 100644 index 0000000..62a07a1 --- /dev/null +++ b/packages/node/native/llama/UPSTREAM_COMMIT @@ -0,0 +1 @@ +e920c523e3b8a0163fe498af5bf90df35ff51d25 diff --git a/packages/node/native/llama/UPSTREAM_LOCK.json b/packages/node/native/llama/UPSTREAM_LOCK.json new file mode 100644 index 0000000..38a8768 --- /dev/null +++ b/packages/node/native/llama/UPSTREAM_LOCK.json @@ -0,0 +1,40 @@ +{ + "schema_version": 1, + "upstream": "https://github.com/ggml-org/llama.cpp.git", + "commit": "e920c523e3b8a0163fe498af5bf90df35ff51d25", + "commit_tree": "6c91a11407a3a3fb160f5dac705f9c59718f54f1", + "patched_tree": "4a37c06fac668834435b803caa59ba272bdace5c", + "upstream_license": "MIT", + "patch_series": [ + "0001-cmake-reserve-meshnet-patch-stack-abi-marker.patch" + ], + "patch_scope": [ + "Reserved CMake ABI marker only; no execution or model semantics." + ], + "build": { + "generator": "Unix Makefiles", + "cmake_minimum": "3.14", + "cxx_standard": "17", + "configure_flags": [ + "-DCMAKE_BUILD_TYPE=Release", + "-DLLAMA_BUILD_TESTS=OFF", + "-DLLAMA_BUILD_EXAMPLES=ON", + "-DLLAMA_BUILD_SERVER=OFF", + "-DLLAMA_BUILD_TOOLS=OFF", + "-DLLAMA_BUILD_APP=OFF", + "-DLLAMA_CURL=OFF" + ], + "native_targets": ["llama-gguf-hash"], + "smoke_binary": "bin/llama-gguf-hash", + "smoke_args": ["--help"], + "smoke_output_token": "usage" + }, + "required_upstream_blobs": { + "CMakeLists.txt": "81f23d7e70b7378511af5d01be680c03aebc2b15" + }, + "patched_paths": [ + "CMakeLists.txt", + "cmake/meshnet-patch-stack.cmake" + ], + "stock_glm_limitations": "This pin may load GLM-5.2 through the dense-MLA compatibility fallback. It does not prove native DSA, IndexShare, MoE semantic correctness, numerical equivalence, performance, or route certification." +} diff --git a/packages/node/native/llama/patches/0001-cmake-reserve-meshnet-patch-stack-abi-marker.patch b/packages/node/native/llama/patches/0001-cmake-reserve-meshnet-patch-stack-abi-marker.patch new file mode 100644 index 0000000..1212065 --- /dev/null +++ b/packages/node/native/llama/patches/0001-cmake-reserve-meshnet-patch-stack-abi-marker.patch @@ -0,0 +1,37 @@ +From d9992f62e852c8647a2ad302009b0339dc1cbf5b Mon Sep 17 00:00:00 2001 +From: DGR-004 +Date: Tue, 14 Jul 2026 09:52:24 +0300 +Subject: [PATCH] cmake: reserve Meshnet patch-stack ABI marker + +--- + CMakeLists.txt | 1 + + cmake/meshnet-patch-stack.cmake | 7 +++++++ + 2 files changed, 8 insertions(+) + +diff --git a/CMakeLists.txt b/CMakeLists.txt +index 81f23d7e..a9afcffa 100644 +--- a/CMakeLists.txt ++++ b/CMakeLists.txt +@@ -123,6 +123,7 @@ option(LLAMA_LLGUIDANCE "llama-common: include LLGuidance library for structured + # Required for relocatable CMake package + include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/build-info.cmake) + include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/common.cmake) ++include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/meshnet-patch-stack.cmake) + + if (NOT DEFINED LLAMA_BUILD_NUMBER) + set(LLAMA_BUILD_NUMBER ${BUILD_NUMBER}) +diff --git a/cmake/meshnet-patch-stack.cmake b/cmake/meshnet-patch-stack.cmake +new file mode 100644 +index 00000000..910646b4 +--- /dev/null ++++ b/cmake/meshnet-patch-stack.cmake +@@ -0,0 +1,7 @@ ++# Reserved, local-only hook for the Meshnet-owned llama.cpp patch series. ++# No execution, protocol, architecture, or model semantic changes are in DGR-004. ++set(LLAMA_MESHNET_PATCH_STACK_VERSION "1" CACHE STRING ++ "Meshnet patch stack ABI marker") ++add_library(llama_meshnet_patch_stack INTERFACE) ++target_compile_definitions(llama_meshnet_patch_stack INTERFACE ++ LLAMA_MESHNET_PATCH_STACK_VERSION=${LLAMA_MESHNET_PATCH_STACK_VERSION}) +-- +2.54.0 diff --git a/packages/node/native/llama/patches/SHA256SUMS b/packages/node/native/llama/patches/SHA256SUMS new file mode 100644 index 0000000..fdbee76 --- /dev/null +++ b/packages/node/native/llama/patches/SHA256SUMS @@ -0,0 +1,2 @@ +# SHA-256 digests for the ordered patch series. Do not reorder this file. +1454216c019c1cb7f78d1d836fe4054164fff1d498391013bcaf13cc2d328c75 0001-cmake-reserve-meshnet-patch-stack-abi-marker.patch diff --git a/packages/node/native/llama/patches/series b/packages/node/native/llama/patches/series new file mode 100644 index 0000000..16f95ea --- /dev/null +++ b/packages/node/native/llama/patches/series @@ -0,0 +1 @@ +0001-cmake-reserve-meshnet-patch-stack-abi-marker.patch diff --git a/scripts/llama_cpp_dependency.py b/scripts/llama_cpp_dependency.py new file mode 100644 index 0000000..f8f6494 --- /dev/null +++ b/scripts/llama_cpp_dependency.py @@ -0,0 +1,267 @@ +#!/usr/bin/env python3 +"""Materialize, verify, build, and smoke-test DGR-004's llama.cpp pin. + +This tool deliberately owns only a source dependency boundary. It never +downloads a model, invokes inference, or interprets generated text. +""" + +from __future__ import annotations + +import argparse +import hashlib +import json +import os +import pathlib +import shutil +import subprocess +import sys +from typing import Any + + +ROOT = pathlib.Path(__file__).resolve().parents[1] +LLAMA_DIR = ROOT / "packages/node/native/llama" +LOCK_PATH = LLAMA_DIR / "UPSTREAM_LOCK.json" +PATCH_DIR = LLAMA_DIR / "patches" + + +def _cmake() -> str: + """Use an explicit override, PATH, or the active Python environment.""" + configured = os.environ.get("CMAKE") + if configured: + return configured + on_path = shutil.which("cmake") + if on_path: + return on_path + sibling = pathlib.Path(sys.executable).parent / "cmake" + if sibling.is_file(): + return str(sibling) + raise DependencyError("cmake is unavailable; set CMAKE or activate the project toolchain") + + +class DependencyError(RuntimeError): + """A fail-closed reproducibility or source-integrity failure.""" + + +def _run(*args: str, cwd: pathlib.Path | None = None) -> str: + try: + completed = subprocess.run( + args, + cwd=cwd, + check=True, + text=True, + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + ) + except FileNotFoundError as error: + raise DependencyError(f"required executable is unavailable: {args[0]}") from error + except subprocess.CalledProcessError as error: + detail = (error.stderr or error.stdout).strip() + raise DependencyError(f"command failed: {' '.join(args)}\n{detail}") from error + return completed.stdout.strip() + + +def _load_lock() -> dict[str, Any]: + try: + lock = json.loads(LOCK_PATH.read_text()) + except (OSError, json.JSONDecodeError) as error: + raise DependencyError(f"invalid upstream lock: {LOCK_PATH}: {error}") from error + required = { + "upstream", "commit", "commit_tree", "patched_tree", "patch_series", + "required_upstream_blobs", "patched_paths", "build", + } + missing = sorted(required - lock.keys()) + if missing: + raise DependencyError(f"upstream lock is missing fields: {', '.join(missing)}") + commit_file = (LLAMA_DIR / "UPSTREAM_COMMIT").read_text().strip() + if lock["commit"] != commit_file or len(commit_file) != 40: + raise DependencyError("UPSTREAM_COMMIT and UPSTREAM_LOCK.json do not agree on a full commit") + return lock + + +def _patches(lock: dict[str, Any]) -> list[pathlib.Path]: + series = [line for line in (PATCH_DIR / "series").read_text().splitlines() if line] + if series != lock["patch_series"] or series != sorted(series) or not series: + raise DependencyError("patches/series is empty, unordered, or disagrees with UPSTREAM_LOCK.json") + sums: dict[str, str] = {} + for line in (PATCH_DIR / "SHA256SUMS").read_text().splitlines(): + if line and not line.startswith("#"): + digest, name = line.split(maxsplit=1) + sums[name] = digest + patches: list[pathlib.Path] = [] + for name in series: + patch = PATCH_DIR / name + if not patch.is_file(): + raise DependencyError(f"patch listed in series is missing: {name}") + actual = hashlib.sha256(patch.read_bytes()).hexdigest() + if sums.get(name) != actual: + raise DependencyError(f"patch digest mismatch for {name}: expected {sums.get(name)}, got {actual}") + patches.append(patch) + return patches + + +def _git(source: pathlib.Path, *args: str) -> str: + return _run("git", "-C", str(source), *args) + + +def _verify_source(source: pathlib.Path, lock: dict[str, Any], *, require_clean: bool) -> None: + if not (source / ".git").exists(): + raise DependencyError(f"not a materialized git checkout: {source}") + if _git(source, "rev-parse", "HEAD") != lock["commit"]: + raise DependencyError("upstream drift: checkout HEAD does not equal the locked commit") + if _git(source, "rev-parse", "HEAD^{tree}") != lock["commit_tree"]: + raise DependencyError("upstream drift: checkout tree does not equal the locked tree") + if require_clean and _git(source, "status", "--porcelain"): + raise DependencyError("local edits detected in materialized llama.cpp checkout") + for relative, expected in lock["required_upstream_blobs"].items(): + actual = _git(source, "rev-parse", f"HEAD:{relative}") + if actual != expected: + raise DependencyError( + f"upstream ABI/context drift for {relative}: expected {expected}, got {actual}" + ) + if not (source / "LICENSE").is_file(): + raise DependencyError("upstream LICENSE is missing; refusing to drop required attribution") + + +def materialize(source: pathlib.Path, repository: str) -> None: + lock = _load_lock() + _patches(lock) + if source.exists(): + raise DependencyError(f"destination already exists; refusing to reuse possibly edited source: {source}") + source.parent.mkdir(parents=True, exist_ok=True) + _run("git", "clone", "--no-checkout", repository, str(source)) + _git(source, "checkout", "--detach", lock["commit"]) + _verify_source(source, lock, require_clean=True) + + +def apply(source: pathlib.Path) -> None: + lock = _load_lock() + patches = _patches(lock) + _verify_source(source, lock, require_clean=True) + for patch in patches: + _git(source, "apply", "--check", str(patch)) + _git(source, "apply", "--index", str(patch)) + _verify_patched_source(source, lock) + + +def _verify_patched_source(source: pathlib.Path, lock: dict[str, Any]) -> None: + if _git(source, "diff", "--quiet"): + raise DependencyError("local unstaged edits detected after applying patch stack") + changed_paths = _git(source, "diff", "--cached", "--name-only").splitlines() + if changed_paths != lock["patched_paths"]: + raise DependencyError(f"patched paths drifted: expected {lock['patched_paths']}, got {changed_paths}") + if _git(source, "write-tree") != lock["patched_tree"]: + raise DependencyError("patched source tree differs from the locked patch stack") + status = _git(source, "status", "--porcelain", "--untracked-files=all").splitlines() + expected_status = [f"M {path}" if path == "CMakeLists.txt" else f"A {path}" for path in lock["patched_paths"]] + if status != expected_status: + raise DependencyError(f"local edits detected after applying patch stack: {status}") + + +def build(source: pathlib.Path, build_dir: pathlib.Path) -> pathlib.Path: + lock = _load_lock() + _patches(lock) + _verify_source(source, lock, require_clean=False) + _verify_patched_source(source, lock) + expected_marker = source / "cmake/meshnet-patch-stack.cmake" + if not expected_marker.is_file(): + raise DependencyError("patch stack is not applied: Meshnet CMake marker is absent") + if build_dir.exists(): + raise DependencyError(f"build directory already exists; use reproduce for a clean rebuild: {build_dir}") + flags = lock["build"]["configure_flags"] + cmake = _cmake() + _run(cmake, "-G", lock["build"]["generator"], "-S", str(source), "-B", str(build_dir), *flags) + for target in lock["build"]["native_targets"]: + _run(cmake, "--build", str(build_dir), "--target", target, "-j2") + metadata = { + "commit": lock["commit"], + "commit_tree": lock["commit_tree"], + "patches": {patch.name: hashlib.sha256(patch.read_bytes()).hexdigest() for patch in _patches(lock)}, + "configure_flags": flags, + "cmake": _run(cmake, "--version").splitlines()[0], + "cxx": _run("c++", "--version").splitlines()[0], + "model_downloads": False, + "semantic_certification": False, + } + (build_dir / "meshnet-build-metadata.json").write_text(json.dumps(metadata, indent=2, sort_keys=True) + "\n") + return build_dir / lock["build"]["smoke_binary"] + + +def smoke(binary: pathlib.Path) -> None: + if not binary.is_file(): + raise DependencyError(f"native smoke binary is missing: {binary}") + smoke_config = _load_lock()["build"] + output = _run(str(binary), *smoke_config["smoke_args"]) + expected = smoke_config["smoke_output_token"] + if expected not in output.lower(): + raise DependencyError(f"native smoke output did not contain {expected!r}: {output}") + print(output) + + +def reproduce(work_dir: pathlib.Path, repository: str) -> None: + resolved = work_dir.resolve() + build_root = (ROOT / "build").resolve() + if build_root not in resolved.parents: + raise DependencyError(f"--work-dir must be below {build_root}: {resolved}") + if resolved.exists(): + raise DependencyError( + f"work directory already exists; refusing to erase possible local edits: {resolved}" + ) + source = resolved / "source" + build_dir = resolved / "build" + materialize(source, repository) + apply(source) + smoke(build(source, build_dir)) + + +def inspect() -> None: + lock = _load_lock() + patches = _patches(lock) + print(json.dumps({ + "commit": lock["commit"], + "patch_count": len(patches), + "patches": [patch.name for patch in patches], + "model_downloads": False, + "semantic_certification": False, + "glm_stock_limitations": lock["stock_glm_limitations"], + }, indent=2, sort_keys=True)) + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__) + subcommands = parser.add_subparsers(dest="command", required=True) + subcommands.add_parser("inspect") + materialize_parser = subcommands.add_parser("materialize") + materialize_parser.add_argument("--source-dir", type=pathlib.Path, required=True) + materialize_parser.add_argument("--source-repository", default=_load_lock()["upstream"]) + apply_parser = subcommands.add_parser("apply") + apply_parser.add_argument("--source-dir", type=pathlib.Path, required=True) + build_parser = subcommands.add_parser("build") + build_parser.add_argument("--source-dir", type=pathlib.Path, required=True) + build_parser.add_argument("--build-dir", type=pathlib.Path, required=True) + smoke_parser = subcommands.add_parser("smoke") + smoke_parser.add_argument("--binary", type=pathlib.Path, required=True) + reproduce_parser = subcommands.add_parser("reproduce") + reproduce_parser.add_argument("--work-dir", type=pathlib.Path, default=ROOT / "build/dgr-004-smoke") + reproduce_parser.add_argument("--source-repository", default=_load_lock()["upstream"]) + args = parser.parse_args() + try: + if args.command == "inspect": + inspect() + elif args.command == "materialize": + materialize(args.source_dir, args.source_repository) + elif args.command == "apply": + apply(args.source_dir) + elif args.command == "build": + build(args.source_dir, args.build_dir) + elif args.command == "smoke": + smoke(args.binary) + else: + reproduce(args.work_dir, args.source_repository) + except DependencyError as error: + print(f"DGR-004 dependency error: {error}", file=sys.stderr) + return 2 + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tests/test_llama_cpp_dependency.py b/tests/test_llama_cpp_dependency.py new file mode 100644 index 0000000..f8621f7 --- /dev/null +++ b/tests/test_llama_cpp_dependency.py @@ -0,0 +1,68 @@ +"""Offline guards for DGR-004's pinned llama.cpp dependency boundary.""" + +from __future__ import annotations + +import hashlib +import json +import pathlib +import subprocess +import sys + + +ROOT = pathlib.Path(__file__).resolve().parents[1] +LLAMA_DIR = ROOT / "packages/node/native/llama" +SCRIPT = ROOT / "scripts/llama_cpp_dependency.py" + + +def _sha256(path: pathlib.Path) -> str: + return hashlib.sha256(path.read_bytes()).hexdigest() + + +def test_lock_and_patch_manifest_are_self_consistent_and_exact() -> None: + lock = json.loads((LLAMA_DIR / "UPSTREAM_LOCK.json").read_text()) + commit = (LLAMA_DIR / "UPSTREAM_COMMIT").read_text().strip() + patches = (LLAMA_DIR / "patches/series").read_text().splitlines() + sums = { + name: digest + for digest, name in ( + line.split(maxsplit=1) + for line in (LLAMA_DIR / "patches/SHA256SUMS").read_text().splitlines() + if line and not line.startswith("#") + ) + } + + assert commit == lock["commit"] + assert len(commit) == 40 + assert patches == lock["patch_series"] + assert patches == sorted(patches) + assert patches + for patch_name in patches: + patch = LLAMA_DIR / "patches" / patch_name + assert sums[patch_name] == _sha256(patch) + assert "Subject: [PATCH" in patch.read_text() + + +def test_dependency_script_reports_the_locked_boundary_without_network() -> None: + completed = subprocess.run( + [sys.executable, str(SCRIPT), "inspect"], + cwd=ROOT, + check=True, + capture_output=True, + text=True, + ) + report = json.loads(completed.stdout) + + assert report["commit"] == (LLAMA_DIR / "UPSTREAM_COMMIT").read_text().strip() + assert report["patch_count"] == 1 + assert report["model_downloads"] is False + assert report["semantic_certification"] is False + assert "dense" in report["glm_stock_limitations"].lower() + + +def test_patch_stack_does_not_contain_meshnet_control_plane_code() -> None: + forbidden = ("tracker", "route session", "grpc", "http", "billing", "wallet") + patch_text = "\n".join( + (LLAMA_DIR / "patches" / name).read_text().lower() + for name in (LLAMA_DIR / "patches/series").read_text().splitlines() + ) + assert not any(term in patch_text for term in forbidden)