Merge branch 'ralph/distributed-gguf-runtime' of https://git.d-popov.com/popov/neuron-tai into ralph/distributed-gguf-runtime

.ralph-tui/config.toml

@@ -1,13 +0,0 @@
-# Ralph TUI Configuration
-# Generated by setup wizard
-# See: ralph-tui config help
-
-configVersion = "2.1"
-tracker = "json"
-agent = "codex"
-model = "gpt-5.6-terra"
-maxIterations = 0
-autoCommit = true
-
-[trackerOptions]
-[agentOptions]

.scratch/distributed-gguf-runtime/PRD.md

@@ -1,252 +1,714 @@
-# PRD: Performant Concurrent Distributed GGUF Runtime
+# PRD: Distributed GGUF Runtime
 
-## Overview
+> **Specification status:** planning artifacts only. No distributed GGUF runtime is implemented. DGR-017 cleanup is complete; no runtime implementation story has completion credit. `prd.json` is authoritative.
 
-Build one lean native GGUF execution path that lets an Inference Route combine consumer machines to serve models larger than any one node can hold. Reuse the existing Meshnet control plane and llama.cpp/GGML execution engine. Adopt gRPC/HTTP2 and Protocol Buffers for the native Shard worker data plane rather than inventing a transport.
+## Goal
 
-The program is benchmark-gated. GGUF is not assumed faster merely because it is quantized or uses a different file format. The first story compares the current Transformers/safetensors backend against whole-model llama.cpp on controlled model/hardware/quality lanes and locks a performance contract. Native distributed work proceeds only when GGUF provides a meaningful speed or fit benefit.
+Deliver benchmark-gated, concurrent, distributed GGUF inference across consumer machines through existing Meshnet control-plane behavior and a standalone native worker around upstream llama.cpp. The accepted target is DeepSeek V4 Flash, not the superseded legacy target.
 
-## Goals
+## Locked scope
 
-- Execute one GGUF model across independently addressable contiguous Shards.
-- Retain Hot KV State locally for each Shard and isolate concurrent Route Sessions.
-- Batch compatible decode steps across active sessions for aggregate throughput.
-- Use consumer CPU, AMD, NVIDIA, Vulkan, Metal, and mixed routes only where a real certified forward passes.
-- Beat the current distributed safetensors route under a controlled performance contract or enable a larger otherwise-unroutable model at useful measured speed.
-- Keep the critical path to Meshnet plus a small pinned llama.cpp fork and standalone C++ worker.
-- Produce narrow upstream collaboration material for llama.cpp without placing Meshnet networking or economics inside upstream.
+- Existing Meshnet Tracker routing, load balancing, billing, telemetry, relay, and provider semantics are backend-agnostic and are **not redesigned**. GGUF contributes exact compatibility, range/capacity, queue/load, seam-cost, health/reliability, and certification inputs only.
+- The data plane is a standalone project-owned C++ Shard worker with gRPC/Protobuf and a project-owned `ShardEngine` boundary.
+- llama.cpp is fetched at one exact commit into an ignored workspace from an in-repo manifest, then a numbered minimal patch stack is applied. There is no submodule, vendored tree, or permanent-fork dependency.
+- llama.cpp owns DeepSeek V4 graphs, mHC, MoE, attention, hash routing, and kernels. Meshnet adds only range-ownership hooks, typed boundary/local-state adapters, worker integration, and parity/certification.
+- Quantization and placement are dynamic recipe inputs. The 2–4 and 10+ stage layouts are certification scenarios, never product constants.
+- Per-shard Hot KV and V4 CSA/HCA/SWA/indexer/compressor state remain local and keyed by route session/epoch. The WAN seam carries the typed mHC 4×4096 residual boundary, positions, token-ID sideband where required, and schema/cache expectations—not per-layer caches.
+- Route changes use cache miss plus re-prefill/restart. There is no WAN KV or V4 auxiliary-cache migration.
+- CPU/CUDA/ROCm/Vulkan/Metal compile lanes are planned; only exact real-hardware-certified backend/model/recipe lanes may be advertised.
+- Alpha requires correctness and the pre-locked useful-speed gate. MTP is reserved and off for alpha; its ownership contract, implementation, and benchmark are required before beta.
 
-## Quality Gates
+## Target identities
 
-Every story must:
+- DeepSeek V4 official target SHA: `60d8d70770c6776ff598c94bb586a859a38244f1`.
+- llama.cpp V4 support lineage began at PR 24162 / merge `8c146a8366304c871efc26057cc90370ccf58dad`; DGR-027 later pins one exact validated current commit.
+- V4 scope: 43 main layers plus MTP; mHC 4×4096 boundary; 256 routed + 1 shared experts with six routed active; token IDs required for the first three hash-routed layers.
+- Exact split-GGUF artifacts are provisioned to mounted-drive storage with a complete hashed manifest and resumable verification; no model artifact may be placed under `/home`.
 
-- Run its targeted `pytest` tests.
-- Run `python -m compileall packages tests` for Python changes.
-- Run `git diff --check`.
-- Keep default tests deterministic, model-download-free, API-credit-free, and GPU-free.
-- Preserve existing Transformers/safetensors behavior unless the story explicitly changes a versioned compatibility contract.
+## Quality gates
 
-Stories touching the native worker must also:
+The canonical gate groups live in `prd.json`. Every story explicitly requires its applicable shared gates: deterministic targeted tests, Python compile checks where applicable, native CMake/CTest and exact patch verification where applicable, real artifact/hardware provenance for opt-in lanes, `git diff --check`, and a durable evidence handoff.
 
-- Build the pinned C++ target with CMake.
-- Run focused C++/protocol tests through CTest or the documented equivalent.
-- Verify the llama.cpp patch stack applies cleanly to the exact pinned commit.
+## Milestones
 
-Real-model/hardware stories must:
+- **M0 — Truth and contracts (DGR-017..DGR-020):** Reconciled legacy truth, canonical metadata, immutable gates, and a controlled whole-model baseline.
+- **M1 — Protocol and native substrate (DGR-021..DGR-033):** Versioned gRPC protocol, exact identities/artifacts, pinned upstream, reproducible builds, ShardEngine, and fake worker.
+- **M2 — Dense vertical proof (DGR-034..DGR-043):** Dense ranged execution, parity, local state, worker integration, and GGUF inputs to existing routing.
+- **M3 — DeepSeek V4 Flash alpha (DGR-044..DGR-054):** Pinned V4 adapter around upstream llama.cpp, real route certification, and pre-locked alpha decision with MTP off.
+- **M4 — Performance and beta hardening (DGR-055..DGR-067):** Batching, backpressure, recovery, scale certification, optimization, MTP, and hardware matrix.
+- **M5 — Release and maintenance (DGR-068..DGR-071):** Reproducible packages, upstream collaboration, beta decision, and sustainable recertification.
 
-- Require `MESHNET_ENABLE_REAL_INFERENCE_TESTS=1`.
-- Use the machine-specific mounted-drive model path and the certified runtime environment; never place model artifacts under `/home`.
-- Record exact model revision, artifact hash, runtime recipe, hardware, driver/backend, commands, raw JSON metrics, and output-quality result.
-- Label synthetic tests as unit coverage rather than distributed acceptance.
+## User stories
 
-Before a story is marked complete, run the full deterministic `pytest -q` suite or record the exact pre-existing unrelated failure with a clean-tree reproduction.
+### DGR-017: Reconcile and clean the superseded DGR backlog
 
-## User Stories
+**Milestone:** M0 · **Mode:** AFK · **State:** complete · **Depends on:** none
 
-### DGR-001: Lock the safetensors-versus-GGUF performance contract
-**Description:** As a runtime engineer, I need a controlled baseline so that GGUF work proceeds from measured speed, memory, and quality rather than reputation.
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/017-reconcile-and-clean-the-superseded-dgr-backlog.md`, and evidence READMEs for dependencies (none) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Audit implementation reality, void inherited completion credit, and clean misleading backlog/stub baggage while preserving attributable evidence and accepted research.
 
-**Acceptance Criteria:**
-- [ ] Benchmark the same model architecture/revision, machine, prompts, context lengths, output lengths, sampling policy, and concurrency across the current Transformers/safetensors recipe and whole-model llama.cpp recipes.
-- [ ] Separate correctness/quality lanes from quantized performance/fit lanes instead of claiming BF16 and Q4 are numerically equivalent.
-- [ ] Report TTFT, prefill tok/s, decode tok/s, p50/p95 latency, aggregate throughput, RSS, VRAM, artifact size, failures, and output drift in machine-readable JSON.
-- [ ] Add concurrency levels 1 and 4 where memory permits.
-- [ ] Write a versioned performance contract consumed by later release gates, including an explicit stop condition when llama.cpp/GGUF has no meaningful speed or fit benefit.
+- [x] Compare the branch, old DGR-001..016 issue/pass states, evidence, and actual runtime sources; classify each output as reusable, reference-only, blocked, obsolete, or absent.
+- [x] Record an authoritative old-to-new disposition and provenance; explicitly give no completion credit to any new story and note absent implementation/evidence.
+- [x] Remove or archive only artifacts the audit proves obsolete while preserving accepted ADRs, useful research, raw benchmark evidence, and attributable reusable work.
+- [x] Protect ignored build workspaces, generated protobuf outputs, Ralph logs, and model artifacts from accidental commits, and document every retained legacy artifact.
+- [x] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
 
-### DGR-002: Adopt the versioned gRPC Shard protocol
-**Description:** As a node developer, I need a battle-proven streaming protocol so that Python and C++ Shards communicate without a custom socket protocol.
+### DGR-018: Define canonical Ralph and Gitea metadata schema
 
-**Acceptance Criteria:**
-- [ ] Add a Protocol Buffers schema for capability, health, session stream, release, and cancellation operations.
-- [ ] Define one long-lived bidirectional gRPC stream per Route Session Activation Seam with deadlines, cancellation, flow control, and structured errors.
-- [ ] Define bounded chunking for prefill and a small decode fast path.
-- [ ] Carry schema version, request/work ID, Route Session ID, route epoch, artifact/recipe fingerprint, Shard range/effective start, phase, position, idempotency step, cache expectation, compression, and checksum.
-- [ ] Define a versioned named-tensor bundle with per-tensor name, shape, dtype, byte order, and payload fragments.
-- [ ] Add generated-schema round-trip and compatibility tests in Python and C++.
+**Milestone:** M0 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-017
 
-### DGR-003: Define exact Artifact and runtime recipe identity
-**Description:** As the Tracker, I need exact compatibility identity so that only numerically and operationally compatible Shards form an Inference Route.
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/018-define-canonical-ralph-and-gitea-metadata-schema.md`, and evidence READMEs for dependencies (DGR-017) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Make `prd.json` the validated source from which Markdown and Gitea issues can later be generated losslessly.
 
-**Acceptance Criteria:**
-- [ ] Separate weight quantization, activation dtype, compute dtype, KV dtype/layout, tokenizer revision, architecture adapter, backend, and runtime version.
-- [ ] Bind derivative or split artifacts to an exact source Model Artifact hash and Shard range.
-- [ ] Produce a stable compatibility fingerprint used by capability admission and the gRPC handshake.
-- [ ] Fail closed on mismatched artifact, tokenizer, architecture, range, boundary schema, activation recipe, or cache layout.
-- [ ] Keep unsupported recipes registered-but-dark until a real distributed forward certifies them.
+- [ ] Define fields for stable ID/title, labels, milestone, type, `dependsOn`, derived `blocks`, triage, evidence class, and hardware/model/upstream flags.
+- [ ] Validate that all stories start `passes: false`, use known dependencies, and have unique stable IDs.
+- [ ] Reject cycles, missing dependencies, mismatched generated `blocks`, duplicate titles/IDs, and generated artifacts claiming authority over `prd.json`.
+- [ ] Add deterministic model-free tests for parse, validation, and generation round trips.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
 
-### DGR-004: Create the reproducible pinned llama.cpp patch stack
-**Description:** As a maintainer, I need a small auditable fork boundary so that upstream updates do not turn the runtime into an unmaintainable stitched codebase.
+### DGR-019: Lock alpha and beta performance contracts
 
-**Acceptance Criteria:**
-- [ ] 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.
+**Milestone:** M0 · **Mode:** HITL · **Triage:** `ready-for-human` · **Depends on:** DGR-017
 
-### DGR-005: Implement dense-Llama range-aware GGUF ownership
-**Description:** As a node, I need to map only my assigned dense-Llama Shard so that aggregate consumer memory can hold a model larger than one node.
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/019-lock-alpha-and-beta-performance-contracts.md`, and evidence READMEs for dependencies (DGR-017) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Freeze useful speed, correctness, memory-fit, and stop/go thresholds before implementation results are visible.
 
-**Acceptance Criteria:**
-- [ ] 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.
+- [ ] Define controlled safetensors, whole-model GGUF, dense distributed GGUF, and V4 Flash distributed lanes with fixed prompts, context/output lengths, sampling, concurrency, hardware, and metrics.
+- [ ] Alpha requires correctness plus a human-approved useful-speed threshold; beta adds concurrency, long-context, failure, and sustained-throughput thresholds.
+- [ ] Separate quantization/model-fit gains from runtime, transport, batching, and kernel gains.
+- [ ] Treat quants and 2–4/10+ stage counts only as named certification scenarios; no product logic may hardcode them.
+- [ ] Lock thresholds and stop conditions in versioned machine-readable data before benchmark result ingestion.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
 
-### DGR-006: Implement architecture-defined boundary input/output
-**Description:** As a Shard, I need to consume and emit the correct transformer boundary state so that disjoint processes reproduce whole-model execution.
+### DGR-020: Run the controlled whole-model GGUF baseline
 
-**Acceptance Criteria:**
-- [ ] Head accepts token IDs and owns token embedding.
-- [ ] Middle/tail bypass token embedding and accept the named boundary bundle.
-- [ ] Non-tail emits the unnormalized architecture-defined residual/boundary before final norm/head and before tail-only row pruning.
-- [ ] Tail emits logits or token output through an explicit sampling contract.
-- [ ] Dense-Llama whole-model versus two-range prefill and greedy-decode parity passes the documented tolerance.
-- [ ] The adapter interface fails closed for uncertified architectures.
+**Milestone:** M0 · **Mode:** HITL · **Triage:** `ready-for-human` · **Depends on:** DGR-019
 
-### DGR-007: Add isolated concurrent local Hot KV State
-**Description:** As a client, I need concurrent Route Sessions to retain independent per-Shard cache so that one request cannot clear or corrupt another.
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/020-run-the-controlled-whole-model-gguf-baseline.md`, and evidence READMEs for dependencies (DGR-019) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Execute the locked safetensors and whole-model llama.cpp lanes before distributed implementation results can influence the decision.
 
-**Acceptance Criteria:**
-- [ ] Map `(Route Session ID, route epoch)` to an isolated llama sequence or bounded context.
-- [ ] Allocate KV only for owned layers.
-- [ ] Support prefill append, decode append, truncate, release, TTL/LRU eviction, and explicit cache-miss response.
-- [ ] Reject stale epochs and incompatible cache recipes.
-- [ ] At least four concurrent sessions on a small model complete without token or KV cross-talk.
-- [ ] Cancellation/release of one session leaves other sessions intact and memory returns to the configured budget.
+- [ ] Run the exact DGR-019 safetensors and whole-model llama.cpp benchmark lanes with locked prompts, lengths, sampling, concurrency, hardware, and artifact/runtime identities.
+- [ ] Record raw machine-readable correctness, TTFT, prefill/decode, throughput, latency, memory, artifact-size, failure, and quality-drift metrics without ingesting distributed implementation results.
+- [ ] Separate quantization/model-fit effects from runtime/kernel effects and preserve failed or unavailable lanes honestly.
+- [ ] Publish a threshold-based `go`, `optimize baseline`, or `stop` decision without changing the locked contract.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
 
-### DGR-008: Build the standalone C++ gRPC Shard worker
-**Description:** As a node runtime, I need one supervised native process so that llama.cpp internals remain behind a stable project-owned protocol.
+### DGR-021: Define the versioned named-tensor stream envelope
 
-**Acceptance Criteria:**
-- [ ] Worker exposes capability, health, session stream, release, cancellation, and metrics services from DGR-002.
-- [ ] Worker loads one exact Artifact/recipe/Shard identity and refuses mismatched requests.
-- [ ] Streaming path enforces bounded messages, flow control, deadlines, idempotency, and independent session cancellation.
-- [ ] Worker does not expose raw llama.cpp RPC or arbitrary GGML graph execution.
-- [ ] Graceful shutdown releases sessions; crash behavior is bounded and observable.
-- [ ] Python integration tests run against a fake model mode without model downloads.
+**Milestone:** M1 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-018
 
-### DGR-009: Integrate the native worker with Meshnet
-**Description:** As the existing node service, I need a GGUF Shard backend adapter so that the Tracker, relay, billing, telemetry, and capability admission remain the sole control plane.
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/021-define-the-versioned-named-tensor-stream-envelope.md`, and evidence READMEs for dependencies (DGR-018) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Establish the backend-neutral protobuf envelope used by direct and relayed Shard activation traffic.
 
-**Acceptance Criteria:**
-- [ ] Implement the existing model-backend surface without changing Transformers behavior.
-- [ ] Registration carries exact validated GGUF recipe, Shard, backend and concurrency/KV capacity.
-- [ ] Tracker forms only complete compatible routes and keeps uncertified recipes dark.
-- [ ] Direct routes use gRPC streams; relayed routes carry the same versioned protobuf frames as opaque binary through the existing relay seam.
-- [ ] Existing request/work IDs, cancellation, Generation Telemetry, billing, and per-node attribution remain correlated.
-- [ ] No vLLM, Nakshatra, prima.cpp, or custom-engine control plane becomes a core dependency.
+- [ ] Define schema version, request/work ID, route session/epoch, shard range/effective start, phase, position, and idempotency step.
+- [ ] Define named tensors with shape, dtype, byte order, bounded fragments, compression identity, and checksum.
+- [ ] Reserve extensible fields for token-ID sidebands, architecture state, recurrent state, and MTP without claiming implementations.
+- [ ] Add deterministic serialization, fragmentation, checksum, unknown-field, and size-limit tests.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
 
-### DGR-010: Pass local real-model two-process acceptance
-**Description:** As a release engineer, I need real local distributed parity before involving network variability.
+### DGR-022: Define Shard lifecycle and structured status RPCs
 
-**Acceptance Criteria:**
-- [ ] Two local worker processes open disjoint dense-Llama ranges from the certified Artifact.
-- [ ] Prefill and at least 32 greedy decode tokens match whole-model llama.cpp within the certified tolerance.
-- [ ] Each worker retains only its own tensors and Hot KV State.
-- [ ] Four concurrent Route Sessions pass isolation and cleanup checks.
-- [ ] Report TTFT, prefill/decode throughput, seam bytes/latency, worker RSS/VRAM, KV memory, batch size, and queue time.
-- [ ] Killing one worker produces a bounded structured failure rather than a deadlock.
+**Milestone:** M1 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-021
 
-### DGR-011: Pass a real heterogeneous two-machine route
-**Description:** As a consumer-hardware operator, I need two physical machines to execute one GGUF model so that the distributed claim is real.
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/022-define-shard-lifecycle-and-structured-status-rpcs.md`, and evidence READMEs for dependencies (DGR-021) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Complete the gRPC contract for worker capability, health, sessions, cancellation, release, and metrics.
 
-**Acceptance Criteria:**
-- [ ] Tracker selects two physical nodes with disjoint Shards and one exact certified recipe/compatibility class.
-- [ ] Actual CPU/GPU execution occurs on both nodes; synthetic workers do not satisfy acceptance.
-- [ ] Prefill/decode, concurrent-session isolation, telemetry, cancellation, and cleanup pass over the real transport/relay path.
-- [ ] Exact hardware, network, backend, model hash, route, commands, and raw metrics are recorded.
-- [ ] A model or recipe larger than one participating node's admitted memory is exercised when available.
-- [ ] Output drift is measured and incompatible mixed backends fail closed.
+- [ ] Define capability, health, bidirectional session stream, cancellation, release, and metrics RPCs.
+- [ ] Specify deadlines, cancellation propagation, bounded flow control, cache expectations/results, and structured error taxonomy.
+- [ ] Specify TLS/auth hooks without moving Meshnet authentication or billing into the worker.
+- [ ] Add compatibility tests for supported versions and fail-closed tests for unsupported versions and malformed lifecycle transitions.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
 
-### DGR-012: Implement continuous batching and bounded admission
-**Description:** As a node operator, I need active sessions batched safely so that concurrency increases aggregate throughput rather than serializing every request.
+### DGR-023: Make Python and C++ protobuf generation reproducible
 
-**Acceptance Criteria:**
-- [ ] Node scheduler admits sessions against weight, KV, scratch, and queue budgets.
-- [ ] Compatible decode steps from multiple sessions form llama.cpp batches while preserving per-session positions and outputs.
-- [ ] Prefill does not starve decode; scheduling policy and bounds are explicit.
-- [ ] Backpressure prevents unbounded queued activations or KV growth.
-- [ ] Capability telemetry reports active sessions, queue depth, batch occupancy, KV pressure, prefill/decode rates, and rejected admissions.
-- [ ] Concurrency 1/2/4/8 benchmark identifies saturation and shows no cross-session corruption.
+**Milestone:** M1 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-021
 
-### DGR-013: Harden failure, cancellation, and restart semantics
-**Description:** As a client, I need failures to be bounded and explicit so that distributed speed does not come with hanging or corrupted generations.
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/023-make-python-and-c-protobuf-generation-reproducible.md`, and evidence READMEs for dependencies (DGR-021) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Generate identical Python/C++ protocol bindings without manual copying or checked-in build debris.
 
-**Acceptance Criteria:**
-- [ ] Deadlines and heartbeat/health loss terminate blocked stream operations.
-- [ ] Cancellation propagates across every Shard and releases local KV and queued buffers.
-- [ ] Duplicate steps are idempotent; uncertain mutations are never replayed silently.
-- [ ] Alpha failover restarts from token zero on a newly compatible route rather than importing unverified KV.
-- [ ] Worker death, stream reset, malformed bundle, stale epoch, and cache miss tests pass.
-- [ ] Billing/work records distinguish completed, cancelled, failed, and unverified work.
+- [ ] Pin protoc, gRPC, and plugin versions or declare a verified compatible range.
+- [ ] Generate Python and C++ bindings into out-of-tree build/package locations through documented commands.
+- [ ] Add Python↔C++ round-trip and descriptor compatibility tests.
+- [ ] A clean checkout regenerates bindings deterministically or fails with an actionable toolchain error.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
 
-### DGR-014: Enforce the GGUF-versus-safetensors release gate
-**Description:** As the product owner, I need an end-to-end comparison so that the native runtime ships only if it advances model access or performance.
+### DGR-024: Implement in-memory fake gRPC seam transport
 
-**Acceptance Criteria:**
-- [ ] Run current distributed safetensors and distributed GGUF routes on the same certified model/hardware/network scenario where technically comparable.
-- [ ] Report quality, TTFT, prefill/decode throughput, aggregate concurrency throughput, p95 latency, seam cost, memory, KV pressure, failures, and cleanup.
-- [ ] Evaluate against the DGR-001 performance contract without changing thresholds after seeing results.
-- [ ] Ship recommendation is one of: promote GGUF, optimize a measured bottleneck with a new bounded task, or stop the native track.
-- [ ] Results clearly separate quantization gains from transport/runtime gains.
+**Milestone:** M1 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-022, DGR-023
 
-### DGR-015: Add and certify a Qwen3/Qwen3-MoE adapter
-**Description:** As a client seeking top models, I need a separately certified MoE-capable architecture after the dense runtime proves stable.
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/024-implement-in-memory-fake-grpc-seam-transport.md`, and evidence READMEs for dependencies (DGR-022, DGR-023) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Exercise the complete streaming protocol deterministically before a real model or worker exists.
 
-**Acceptance Criteria:**
-- [ ] Implement explicit tensor ownership, router/top-k, expert/shared-expert, Q/K normalization, boundary bundle, and cache semantics for the selected Qwen3 family recipe.
-- [ ] Do not reuse the dense-Llama adapter through unchecked name substitutions.
-- [ ] Whole-model versus distributed prefill/decode parity passes the architecture-specific tolerance.
-- [ ] Expert memory ownership and communication are measured.
-- [ ] Real consumer-hardware acceptance and capability admission pass before the recipe becomes routable.
+- [ ] Provide a fake bidirectional stream supporting prefill fragments, decode fast-path frames, release, cancel, and structured errors.
+- [ ] Test flow-control blocking, deadlines, malformed fragments, checksum failure, duplicates, and stale epochs.
+- [ ] Verify direct and opaque-relay framing preserve identical protobuf bytes.
+- [ ] Tests require no sockets outside localhost, model downloads, or native accelerator.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
 
-### DGR-016: Produce the upstream llama.cpp collaboration package
-**Description:** As a maintainer, I need narrow upstreamable proposals so that our patch burden can shrink without asking llama.cpp to own Meshnet networking.
+### DGR-025: Define exact artifact and runtime recipe identity
 
-**Acceptance Criteria:**
-- [ ] Separate generic llama.cpp hooks from Meshnet protocol/control-plane code.
-- [ ] Prepare minimal reproducible examples and tests for range-aware loading, boundary input/output, and layer-filtered KV.
-- [ ] Compare the proposal with Nakshatra and prima.cpp evidence and explain why the API is generally useful.
-- [ ] Preserve one scoped commit/patch per concern against the exact upstream pin.
-- [ ] Produce an outreach document suitable for Georgi/llama.cpp maintainers; actual sending remains a human action.
+**Milestone:** M1 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-018, DGR-021
 
-## Functional Requirements
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/025-define-exact-artifact-and-runtime-recipe-identity.md`, and evidence READMEs for dependencies (DGR-018, DGR-021) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Ensure the tracker and worker only combine numerically and operationally compatible shards.
 
-1. The public distributed primitive is an ordered Inference Route of contiguous Shards.
-2. The native runtime uses llama.cpp/GGML; vLLM remains optional as a complete managed provider.
-3. Native worker communication uses gRPC/HTTP2 and Protocol Buffers with one stable stream per Route Session Activation Seam.
-4. Artifact identity, runtime recipe, boundary schema, activation dtype and cache layout must match exactly before routing.
-5. Hot KV State remains local to the node serving the Shard.
-6. Multiple Route Sessions must execute concurrently without shared-cache corruption.
-7. Nodes batch compatible active decode steps and enforce bounded admission/backpressure.
-8. Unsupported architectures and hardware recipes remain non-routable until real certification passes.
-9. Default tests never download models or require GPUs; real tests are explicit and preserve artifacts off `/home`.
-10. The release decision is based on measured performance, fit, quality, concurrency, and reliability relative to the safetensors baseline.
+- [ ] Fingerprint source artifact SHA, tokenizer revision, architecture adapter/version, boundary schema, runtime pin/patch stack, backend, quant, activation/compute dtype, and KV/state layout.
+- [ ] Bind each shard to an exact half-open range without hardcoding a topology or quant.
+- [ ] Fail closed on any artifact, adapter, boundary, cache, backend, or runtime mismatch.
+- [ ] Unsupported recipes remain registered-but-dark until real-hardware evidence certifies them.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
 
-## Non-Goals
+### DGR-026: Provision exact split-GGUF artifacts outside /home
 
-- Forking vLLM or importing its PagedAttention/Torch distributed runtime.
-- Adopting Nakshatra, prima.cpp, llama-gguf, LiGGUF, or GPUStack as the control plane.
-- Public WAN tensor/expert parallel collectives.
-- QUIC, WebRTC, or a custom socket protocol.
-- Automatic KV migration or mid-generation route repair in the first release.
-- Speculative decoding or disaggregated prefill before the core release gate.
-- Supporting every GGUF architecture before dense Llama and Qwen3-family certification.
-- A marketing-scale model demo that bypasses parity, concurrency, admission, or performance gates.
+**Milestone:** M1 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-025
 
-## Success Metrics
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/026-provision-exact-split-gguf-artifacts-outside-home.md`, and evidence READMEs for dependencies (DGR-025) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Make exact split-GGUF inputs reproducibly available from mounted-drive storage without embedding a quantization or topology assumption in product code.
 
-- A real model larger than one admitted node can execute across consumer machines when suitable hardware/artifacts are available.
-- Four or more concurrent sessions complete without cross-talk; hardware-specific saturation is measured.
-- Distributed GGUF passes the locked performance/fit contract against the existing safetensors route.
-- Worker and Tracker recover all resources after completion, cancellation, malformed input, and node failure.
-- The critical runtime remains Meshnet plus one standalone worker and a small auditable llama.cpp patch stack.
+- [ ] Create an exact manifest that binds the source artifact, tokenizer/revision, every split file name, size, range/role, and cryptographic hash.
+- [ ] Provide resumable, hash-verifying download/provision tooling targeting configured mounted-drive storage; refuse paths under `/home` and incomplete or mismatched splits.
+- [ ] Keep quantization and split topology as manifest/recipe inputs with no hardcoded quant, node count, or range layout.
+- [ ] Add deterministic model-download-free tests using tiny local split fixtures, including interrupted resume, missing split, hash mismatch, and `/home` rejection.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
 
-## Open Questions
+### DGR-027: Add exact llama.cpp provenance manifest and fetch workspace
 
-- Exact benchmark model and quantization lanes are selected by DGR-001 from currently supported, legally redistributable artifacts.
-- Final hardware-specific concurrency and useful-speed thresholds are locked by measured baselines rather than guessed globally.
-- Upstream llama.cpp acceptance is desirable but not a prerequisite for the first narrow pinned fork.
+**Milestone:** M1 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-017
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/027-add-exact-llama-cpp-provenance-manifest-and-fetch-workspace.md`, and evidence READMEs for dependencies (DGR-017) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Pin llama.cpp exactly through an in-repo manifest while fetching source only into an ignored build workspace.
+
+- [ ] Manifest records upstream URL, exact commit, expected source archive/tree hash, license, and retrieval method.
+- [ ] Fetch tooling verifies identity before use and refuses an unpinned branch/tag.
+- [ ] Source is fetched into an ignored build workspace; no submodule, vendored source tree, or permanent fork is introduced.
+- [ ] Offline reuse is supported only after the cached tree’s exact identity is verified.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-028: Implement numbered patch-stack apply and verification
+
+**Milestone:** M1 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-027
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/028-implement-numbered-patch-stack-apply-and-verification.md`, and evidence READMEs for dependencies (DGR-027) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Maintain a minimal auditable llama.cpp delta with one numbered patch per concern.
+
+- [ ] Add deterministic apply/check/reverse verification against the exact manifest pin.
+- [ ] Separate range loading, boundary I/O, filtered state, and worker hooks into scoped patches.
+- [ ] Record upstream file/API assumptions and fail with the first incompatible patch when the pin changes.
+- [ ] Verify license/attribution and prove no Meshnet routing, billing, relay, or authentication code enters the patch stack.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-029: Create the native CMake skeleton and deterministic CPU lane
+
+**Milestone:** M1 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-027, DGR-028
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/029-create-the-native-cmake-skeleton-and-deterministic-cpu-lane.md`, and evidence READMEs for dependencies (DGR-027, DGR-028) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Establish an out-of-tree standalone native build with a deterministic CPU lane before accelerator matrix work.
+
+- [ ] Create the standalone native CMake target/skeleton and isolated out-of-tree configure/build preset for CPU.
+- [ ] Build and run a deterministic model-free CPU smoke/CTest lane from a clean checkout with actionable toolchain failures.
+- [ ] Keep fetched upstream sources, generated bindings, and all build outputs ignored and out of tree.
+- [ ] Ensure build success alone does not advertise any backend/model/recipe capability.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-030: Add accelerator build presets and native CI matrix
+
+**Milestone:** M1 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-029
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/030-add-accelerator-build-presets-and-native-ci-matrix.md`, and evidence READMEs for dependencies (DGR-029) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Compile all required accelerator lanes reproducibly while keeping untested real-hardware capabilities registered-dark.
+
+- [ ] Add isolated out-of-tree presets for CUDA, ROCm, Vulkan, and Metal without changing the deterministic CPU default.
+- [ ] Add a native CI/build matrix that reports unavailable SDKs as explicit unavailable/skipped lanes rather than false success.
+- [ ] Compile each available lane and preserve exact compiler, SDK, upstream pin, patch-stack, and build-option evidence.
+- [ ] Keep every backend/model/recipe lane registered-dark until a separate real-hardware certification record exists.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-031: Introduce the project-owned `ShardEngine` interface
+
+**Milestone:** M1 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-021, DGR-025
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/031-introduce-the-project-owned-shardengine-interface.md`, and evidence READMEs for dependencies (DGR-021, DGR-025) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Isolate worker/protocol code from llama.cpp internals behind a stable project-owned engine contract.
+
+- [ ] Define load, capabilities, prefill/decode, boundary/logits result, cancel, release, health, and metrics operations.
+- [ ] Use project-owned request/result/state types; expose no `ggml_tensor`, llama context, scheduler, or ABI-owned structure.
+- [ ] Reserve typed MTP and architecture auxiliary-state hooks without enabling them.
+- [ ] Add contract tests proving fake and future llama implementations obey identical lifecycle semantics.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-032: Implement deterministic fake `ShardEngine`
+
+**Milestone:** M1 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-031
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/032-implement-deterministic-fake-shardengine.md`, and evidence READMEs for dependencies (DGR-031) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Provide an engine fixture that deterministically transforms typed boundary bundles and session state.
+
+- [ ] Support head, middle, tail, prefill, decode, cancellation, and release with deterministic outputs.
+- [ ] Model isolated session/epoch state and deterministic cache-miss/stale-epoch failures.
+- [ ] Support configurable delay, memory pressure, malformed output, and crash injection.
+- [ ] Contract tests distinguish fixture evidence from real-model certification.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-033: Build a standalone fake C++ gRPC Shard worker
+
+**Milestone:** M1 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-022, DGR-024, DGR-032
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/033-build-a-standalone-fake-c-grpc-shard-worker.md`, and evidence READMEs for dependencies (DGR-022, DGR-024, DGR-032) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Prove the standalone worker process, stream, lifecycle, and supervision shape before llama.cpp integration.
+
+- [ ] A standalone C++ executable serves the complete lifecycle and stream RPC contract using the fake engine.
+- [ ] Python integration tests cover startup, health, capability, fragmented prefill, decode, release, cancellation, and graceful shutdown.
+- [ ] Bounded messages, deadlines, flow control, and independent session cancellation are enforced.
+- [ ] The worker exposes neither llama.cpp RPC nor arbitrary graph execution.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-034: Implement dense-Llama range-aware GGUF ownership
+
+**Milestone:** M2 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-028, DGR-029, DGR-031
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/034-implement-dense-llama-range-aware-gguf-ownership.md`, and evidence READMEs for dependencies (DGR-028, DGR-029, DGR-031) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Load only the dense-Llama tensors owned by a shard range.
+
+- [ ] Load only `blk.N.*` tensors in the assigned range, embeddings only at the head, and norm/output or tied output only at the tail.
+- [ ] Derive authoritative range and endpoint ownership from the loaded engine state.
+- [ ] Reject invalid/gapped/out-of-model ranges and unexpected required tensors.
+- [ ] Real-model evidence shows mapped/resident memory scales with owned tensors rather than full artifact size.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-035: Implement dense architecture boundary input/output
+
+**Milestone:** M2 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-021, DGR-031, DGR-034
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/035-implement-dense-architecture-boundary-input-output.md`, and evidence READMEs for dependencies (DGR-021, DGR-031, DGR-034) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Execute dense head/middle/tail ranges through an architecture-defined residual boundary.
+
+- [ ] Head accepts token IDs and owns embedding; middle/tail bypass embedding and accept a named boundary bundle.
+- [ ] Non-tail returns the unnormalized residual before final norm/head and before tail-only row pruning.
+- [ ] Tail returns logits or sampled-token output under an explicit contract.
+- [ ] Uncertified architectures and incompatible boundary schemas fail closed.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-036: Prove dense fixture and real-model range parity
+
+**Milestone:** M2 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-033, DGR-035
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/036-prove-dense-fixture-and-real-model-range-parity.md`, and evidence READMEs for dependencies (DGR-033, DGR-035) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Prove the engine/protocol seam before adding session concurrency.
+
+- [ ] Model-free two-stage tests pass through two fake worker processes with disjoint ranges.
+- [ ] A small real dense GGUF passes whole-model versus two-range prefill parity.
+- [ ] At least 32 greedy decode tokens match the locked tolerance.
+- [ ] Evidence distinguishes deterministic fixture proof from opt-in real-model proof.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-037: Bind llama.cpp to the standalone worker
+
+**Milestone:** M2 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-022, DGR-023, DGR-031, DGR-034, DGR-035
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/037-bind-llama-cpp-to-the-standalone-worker.md`, and evidence READMEs for dependencies (DGR-022, DGR-023, DGR-031, DGR-034, DGR-035) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Replace the fake engine with the pinned llama.cpp `ShardEngine` implementation without changing the public worker contract.
+
+- [ ] Worker loads exactly one artifact/recipe/range identity and rejects mismatched stream requests.
+- [ ] All execution passes through `ShardEngine`; llama.cpp implementation types remain private.
+- [ ] Health and metrics expose loaded identity, authoritative ownership, memory, and execution state.
+- [ ] Graceful shutdown releases model/session resources; injected process death is observable and bounded.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-038: Implement isolated shard-local Hot KV State
+
+**Milestone:** M2 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-037
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/038-implement-isolated-shard-local-hot-kv-state.md`, and evidence READMEs for dependencies (DGR-037) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Map each route session and epoch to isolated state containing only locally owned layers.
+
+- [ ] Map `(route_session_id, route_epoch)` to an isolated llama sequence or bounded context.
+- [ ] Support prefill/decode append, truncate, release, TTL/LRU eviction, cache miss, and stale-epoch rejection.
+- [ ] Four concurrent sessions complete without token, KV, position, or cancellation cross-talk.
+- [ ] Release/eviction returns memory to the configured budget without affecting other sessions.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-039: Pass local two-process dense acceptance
+
+**Milestone:** M2 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-036, DGR-037, DGR-038
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/039-pass-local-two-process-dense-acceptance.md`, and evidence READMEs for dependencies (DGR-036, DGR-037, DGR-038) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Establish the first real, independently executing distributed GGUF route on one host.
+
+- [ ] Two worker processes open disjoint dense ranges and both execute real prefill/decode work.
+- [ ] Whole-model parity, 32-token greedy decode, four-session isolation, cancellation, and cleanup pass.
+- [ ] Record TTFT, prefill/decode rates, seam bytes/latency, RSS/VRAM, KV, queue, and failure metrics.
+- [ ] Killing one worker returns a bounded structured failure rather than hanging.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-040: Add node-side native worker supervision
+
+**Milestone:** M2 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-033, DGR-037
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/040-add-node-side-native-worker-supervision.md`, and evidence READMEs for dependencies (DGR-033, DGR-037) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Let the existing node service safely start, probe, stop, and restart the standalone worker.
+
+- [ ] Supervision owns process startup, readiness, log capture, graceful shutdown, and bounded forced termination.
+- [ ] Startup verifies worker binary, artifact identity, recipe, and range before registration.
+- [ ] Crashes or health loss make the capability unavailable without corrupting the Transformers backend.
+- [ ] Tests use the fake worker and deterministic crash injection.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-041: Register native Shard capabilities without redesigning Meshnet
+
+**Milestone:** M2 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-025, DGR-040
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/041-register-native-shard-capabilities-without-redesigning-meshnet.md`, and evidence READMEs for dependencies (DGR-025, DGR-040) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Adapt native worker identity and capacity to existing backend-agnostic capability admission.
+
+- [ ] Registration carries exact recipe fingerprint, authoritative range, backend, memory/KV capacity, concurrency, and certification status.
+- [ ] Existing tracker, billing, routing, telemetry, and provider semantics remain backend-agnostic.
+- [ ] Uncertified backend/model/recipe combinations are visible but unroutable.
+- [ ] Existing Transformers registration and route tests remain unchanged in behavior.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-042: Carry native frames through direct and existing relay seams
+
+**Milestone:** M2 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-024, DGR-040
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/042-carry-native-frames-through-direct-and-existing-relay-seams.md`, and evidence READMEs for dependencies (DGR-024, DGR-040) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Use direct gRPC where available and the existing relay as opaque protobuf transport without redesigning relay behavior.
+
+- [ ] Direct paths use the long-lived gRPC activation stream.
+- [ ] Relayed paths carry byte-identical versioned protobuf frames through the existing relay contract.
+- [ ] Request/work identity, cancellation, deadlines, telemetry, billing correlation, and per-node attribution survive both paths.
+- [ ] Fake-worker tests cover direct, relay, disconnect, cancellation, and bounded buffering.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-043: Expose GGUF compatibility and measured cost inputs to existing routing
+
+**Milestone:** M2 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-041
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/043-expose-gguf-compatibility-and-measured-cost-inputs-to-existing-routing.md`, and evidence READMEs for dependencies (DGR-041) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Adapt exact GGUF recipe/range compatibility and measured capacity, queue, seam-cost, health, and reliability data into the existing backend-agnostic routing inputs without redesigning routing or load balancing.
+
+- [ ] Expose exact recipe, range coverage, capacity, queue/load, seam-cost, health, reliability, backend, and certification measurements through existing tracker input contracts.
+- [ ] Prove existing routing forms complete compatible coverage and excludes dark or mismatched candidates using its current backend-agnostic mechanisms.
+- [ ] Regression-test unchanged Transformers behavior and unchanged tracker routing, load-balancing, billing, relay, and provider semantics.
+- [ ] Regression-test that no quant, stage count, fixed split, architecture, backend sequence, or DeepSeek-specific policy is hardcoded.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-044: Pin the DeepSeek V4 Flash target contract
+
+**Milestone:** M3 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-019, DGR-025, DGR-026, DGR-027
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/044-pin-the-deepseek-v4-flash-target-contract.md`, and evidence READMEs for dependencies (DGR-019, DGR-025, DGR-026, DGR-027) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Fix the alpha/beta model identity and upstream maturity assumptions before implementing the adapter.
+
+- [ ] Pin Hugging Face target SHA `60d8d70770c6776ff598c94bb586a859a38244f1`.
+- [ ] Record the selected GGUF provenance and exact source binding without assuming one quant.
+- [ ] Record that llama.cpp support began with PR 24162/commit `8c146a8` and remains maturing; the build manifest still pins one exact validated upstream commit.
+- [ ] Record 43 main layers plus MTP and all known architecture-specific state obligations.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-045: Inventory V4 GGUF tensors and layer ownership
+
+**Milestone:** M3 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-026, DGR-044
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/045-inventory-v4-gguf-tensors-and-layer-ownership.md`, and evidence READMEs for dependencies (DGR-026, DGR-044) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Derive exact head, repeated-layer, tail, expert, auxiliary-state, and MTP ownership from the pinned artifact.
+
+- [ ] Produce a machine-readable inventory tied to the target SHA and exact GGUF artifact.
+- [ ] Classify embeddings, 43 main layers, final head, MTP, mHC, attention variants, indexer/compressor, and MoE tensors.
+- [ ] Validate half-open range ownership and fail on unclassified required tensors.
+- [ ] Inventory tooling works across quants without embedding quant names in architecture logic.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-046: Define the V4 typed architecture boundary schema
+
+**Milestone:** M3 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-021, DGR-045
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/046-define-the-v4-typed-architecture-boundary-schema.md`, and evidence READMEs for dependencies (DGR-021, DGR-045) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Define the exact cross-stage V4 architecture boundary while keeping per-layer attention and auxiliary caches shard-local.
+
+- [ ] Define a versioned named bundle for the mHC 4×4096 residual boundary, positions, token-ID sideband where required, and schema/cache expectations.
+- [ ] Explicitly exclude per-layer CSA, HCA, SWA, indexer, compressor, KV, and MTP caches/state from the WAN boundary; those remain local to the owning shard and session/epoch.
+- [ ] Reserve typed MTP boundary fields but mark MTP execution unsupported and unroutable for alpha.
+- [ ] Fingerprint independently of quant/topology and fail closed on missing, incompatible, incorrectly shaped, or stale boundary/cache expectations.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-047: Adapt the upstream V4 mHC boundary for ranged ownership
+
+**Milestone:** M3 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-045, DGR-046
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/047-adapt-the-upstream-v4-mhc-boundary-for-ranged-ownership.md`, and evidence READMEs for dependencies (DGR-045, DGR-046) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Add range-boundary adapters around upstream llama.cpp V4 mHC execution without reimplementing the V4 graph or kernels.
+
+- [ ] Represent and validate the upstream V4 4×4096 mHC boundary without flattening semantic axes.
+- [ ] Add only head/intermediate/tail range ownership and boundary conversion hooks around the pinned upstream llama.cpp graph.
+- [ ] Compare deterministic fixture vectors and single-process ranged outputs with upstream whole-model execution.
+- [ ] Document that llama.cpp owns V4 mHC graph/kernels and that quantized storage does not alter the logical boundary schema.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-048: Carry token-ID sideband through the first three hash-routed layers
+
+**Milestone:** M3 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-046, DGR-047
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/048-carry-token-id-sideband-through-the-first-three-hash-routed-layers.md`, and evidence READMEs for dependencies (DGR-046, DGR-047) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Ensure any stage containing the first three hash-routed layers receives exact token identities.
+
+- [ ] Head emits token IDs in the typed sideband for boundaries that require them.
+- [ ] Intermediate stages preserve or consume the sideband according to their layer range.
+- [ ] Routes splitting before, within, and after the first three layers pass deterministic partition tests.
+- [ ] Missing or mismatched token IDs fail closed rather than silently selecting incorrect experts.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-049: Keep V4 attention and auxiliary state shard-local
+
+**Milestone:** M3 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-046, DGR-047
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/049-keep-v4-attention-and-auxiliary-state-shard-local.md`, and evidence READMEs for dependencies (DGR-046, DGR-047) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Bind V4 CSA/HCA/SWA/indexer/compressor and KV state to the owning shard session/epoch rather than transferring caches over the WAN.
+
+- [ ] Map CSA, HCA, SWA, indexer, compressor, and KV ownership from the pinned upstream graph to each owned layer range.
+- [ ] Key all such caches/state by route session and epoch with bounded lifecycle, memory accounting, stale-epoch rejection, release, and eviction.
+- [ ] Prove cross-stage messages carry only the typed architecture boundary and cache expectations, never per-layer cache contents.
+- [ ] On route change or state loss, use explicit cache miss and re-prefill/restart; do not migrate V4 caches across workers.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-050: Validate upstream V4 MoE and hash-routing execution under ranged ownership
+
+**Milestone:** M3 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-045, DGR-047
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/050-validate-upstream-v4-moe-and-hash-routing-execution-under-ranged-ownership.md`, and evidence READMEs for dependencies (DGR-045, DGR-047) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Validate the pinned upstream llama.cpp V4 MoE and hash-routing graph when layers are range-owned, without reimplementing routing or expert kernels in Meshnet.
+
+- [ ] Load range-owned tensors for 256 routed plus one shared expert and validate upstream execution activates six routed experts where specified.
+- [ ] Validate the first three upstream hash-routed layers receive exact token-ID sideband across splits before, within, and after them.
+- [ ] Compare upstream whole-model and ranged router/expert outputs, shared-expert contribution, and malformed sideband failures.
+- [ ] Document that llama.cpp owns V4 MoE, attention, hash routing, graph, and kernels; no expert-parallel WAN collective or Meshnet reimplementation is introduced.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-051: Assemble the DeepSeek V4 Flash `ShardEngine` adapter
+
+**Milestone:** M3 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-034, DGR-037, DGR-047, DGR-048, DGR-049, DGR-050
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/051-assemble-the-deepseek-v4-flash-shardengine-adapter.md`, and evidence READMEs for dependencies (DGR-034, DGR-037, DGR-047, DGR-048, DGR-049, DGR-050) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Assemble range ownership hooks and boundary/local-state adapters around upstream llama.cpp V4 execution behind the stable ShardEngine interface.
+
+- [ ] Support valid head, middle, tail, and whole-model ranges over all 43 main layers using the pinned upstream llama.cpp V4 graph/kernels.
+- [ ] Integrate exact range ownership, mHC boundary, positions, required token-ID sideband, and shard-local session/epoch state adapters.
+- [ ] Report MTP reserved-but-not-executable for alpha and reject unsupported split points or cache expectations.
+- [ ] Include exact adapter/schema/runtime/artifact identity and valid split restrictions without reimplementing V4 MoE, attention, mHC, or hash routing.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-052: Pass local V4 whole-model versus ranged parity
+
+**Milestone:** M3 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-038, DGR-051
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/052-pass-local-v4-whole-model-versus-ranged-parity.md`, and evidence READMEs for dependencies (DGR-038, DGR-051) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Prove V4 prefill and decode correctness locally before network certification.
+
+- [ ] Compare pinned whole-model llama.cpp with at least two valid ranged partitions.
+- [ ] Prefill intermediates and locked-length greedy decode pass architecture-specific tolerances.
+- [ ] Test splits around the first three hash-routed layers and at least one CSA/HCA/SWA/indexer/compressor transition.
+- [ ] Four concurrent sessions pass KV/state isolation and cleanup.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-053: Certify a real 2–4-stage V4 route
+
+**Milestone:** M3 · **Mode:** HITL · **Triage:** `ready-for-human` · **Depends on:** DGR-030, DGR-043, DGR-052
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/053-certify-a-real-2-4-stage-v4-route.md`, and evidence READMEs for dependencies (DGR-030, DGR-043, DGR-052) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Prove real Tracker-selected V4 execution across physical machines before alpha.
+
+- [ ] Run one documented 2–4-stage certification scenario using exact compatible artifacts/recipes; the count and chosen quant are evidence inputs, not product constants.
+- [ ] Actual CPU/GPU work executes on every stage; fake workers do not satisfy acceptance.
+- [ ] Record parity, TTFT, prefill/decode speed, seam cost, memory, cache/state isolation, cancellation, and cleanup.
+- [ ] Tracker selection remains dynamic and rejects an injected incompatible backend/recipe.
+- [ ] Only the exact real-hardware lanes exercised become eligible for advertisement.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-054: Enforce the DeepSeek V4 Flash alpha gate
+
+**Milestone:** M3 · **Mode:** HITL · **Triage:** `ready-for-human` · **Depends on:** DGR-017, DGR-019, DGR-020, DGR-039, DGR-042, DGR-043, DGR-052, DGR-053
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/054-enforce-the-deepseek-v4-flash-alpha-gate.md`, and evidence READMEs for dependencies (DGR-017, DGR-019, DGR-020, DGR-039, DGR-042, DGR-043, DGR-052, DGR-053) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Release alpha only when V4 is correct and clears the pre-locked useful-speed requirement.
+
+- [ ] Evaluate correctness, model fit, TTFT, prefill/decode speed, seam cost, memory, and failure rate against DGF-004 without changing thresholds.
+- [ ] Separate quant/model-fit gains from runtime/transport gains.
+- [ ] Decision is `alpha`, `optimize measured bottleneck`, or `stop`; failures cannot be relabeled as certification.
+- [ ] Alpha documentation states MTP is reserved but not implemented and identifies every dark hardware lane.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-055: Implement compatible continuous decode batching
+
+**Milestone:** M4 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-038, DGR-040, DGR-054
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/055-implement-compatible-continuous-decode-batching.md`, and evidence READMEs for dependencies (DGR-038, DGR-040, DGR-054) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Batch compatible active sessions without violating route, recipe, position, or architecture state.
+
+- [ ] Batch only sessions with compatible engine, recipe, phase, boundary schema, and state layout.
+- [ ] Preserve per-session positions, sequence IDs, outputs, cancellation, and accounting.
+- [ ] Decode receives bounded service while prefill remains schedulable.
+- [ ] Deterministic 1/2/4/8 concurrency tests show no cross-session corruption.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-056: Enforce bounded admission, queues, and backpressure
+
+**Milestone:** M4 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-055
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/056-enforce-bounded-admission-queues-and-backpressure.md`, and evidence READMEs for dependencies (DGR-055) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Prevent weight, KV, state, scratch, and stream buffers from exceeding admitted capacity.
+
+- [ ] Admission accounts separately for weights, KV/state, scratch, in-flight fragments, and queue slots.
+- [ ] Queue and stream limits produce structured retryable or terminal responses.
+- [ ] Prefill cannot starve decode and one route session cannot monopolize queue capacity.
+- [ ] Telemetry reports active sessions, queue depth/time, batch occupancy, memory pressure, and rejects.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-057: Benchmark batching saturation and fairness
+
+**Milestone:** M4 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-055, DGR-056
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/057-benchmark-batching-saturation-and-fairness.md`, and evidence READMEs for dependencies (DGR-055, DGR-056) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Identify useful concurrency and saturation points without assuming one global batch size.
+
+- [ ] Run controlled concurrency 1/2/4/8 and record aggregate throughput, per-request p50/p95, TTFT, queue time, occupancy, and memory.
+- [ ] Measure dense and V4 lanes separately where hardware permits.
+- [ ] Verify bounded fairness and no prefill/decode starvation.
+- [ ] Produce machine-readable saturation recommendations consumed by capability reporting, not hardcoded constants.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-058: Harden worker and stream failure semantics
+
+**Milestone:** M4 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-040, DGR-042, DGR-056
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/058-harden-worker-and-stream-failure-semantics.md`, and evidence READMEs for dependencies (DGR-040, DGR-042, DGR-056) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Ensure malformed input, process death, transport reset, and cancellation terminate cleanly.
+
+- [ ] Test worker death, stream reset, malformed bundle, checksum failure, deadline, cache miss, stale epoch, and partial fragment loss.
+- [ ] Cancellation propagates across all stages and releases KV/state, queue entries, and fragment buffers.
+- [ ] Duplicate steps are idempotent; uncertain mutations are never silently replayed.
+- [ ] Billing/work outcomes distinguish completed, cancelled, failed, and unverified work.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-059: Implement alpha-safe route recovery
+
+**Milestone:** M4 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-043, DGR-058
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/059-implement-alpha-safe-route-recovery.md`, and evidence READMEs for dependencies (DGR-043, DGR-058) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Recover from route loss without importing or continuing unverified state.
+
+- [ ] On route loss or local-state cache miss, restart from token zero or re-prefill on a newly compatible route according to the locked alpha contract.
+- [ ] Never import KV, CSA, HCA, SWA, indexer, compressor, recurrent, or MTP cache/state across workers.
+- [ ] Keep exact same-route duplicate delivery idempotent while cross-route continuation fails closed.
+- [ ] Test direct/relay loss, cache miss, replacement selection, client cancellation, and billing reconciliation.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-060: Certify V4 long-context state correctness
+
+**Milestone:** M4 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-051, DGR-056, DGR-058
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/060-certify-v4-long-context-state-correctness.md`, and evidence READMEs for dependencies (DGR-051, DGR-056, DGR-058) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Prove V4’s KV and auxiliary state remain correct and bounded at long contexts.
+
+- [ ] Exercise pre-locked context lengths covering multiple prefill chunks and sustained decode.
+- [ ] Validate KV plus CSA/HCA/SWA/indexer/compressor state positions across every stage.
+- [ ] Measure memory growth, fragment sizes, TTFT, decode degradation, cancellation latency, and cleanup.
+- [ ] Cache mismatch, truncation, and context-limit behavior fail deterministically.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-061: Certify existing routing with 10+ GGUF stage candidates
+
+**Milestone:** M4 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-043, DGR-057, DGR-058
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/061-certify-existing-routing-with-10-gguf-stage-candidates.md`, and evidence READMEs for dependencies (DGR-043, DGR-057, DGR-058) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Certify that existing backend-agnostic routing consumes GGUF compatibility and measured-cost inputs for a 10+ candidate scenario without algorithm or policy redesign.
+
+- [ ] Generate deterministic pools with 10+ compatible GGUF stage candidates plus slower, overloaded, unhealthy, and incompatible alternatives.
+- [ ] Run the existing routing implementation unchanged and verify complete coverage, compatibility, acyclicity, and use of measured inputs.
+- [ ] Regression-test that no stage count, quant, fixed split, architecture, or backend sequence is encoded in production routing policy.
+- [ ] Verify existing route recomputation reacts to measured load/failure while tracker, load-balancing, billing, relay, and provider semantics remain unchanged.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-062: Certify a dynamic real 10+ stage V4 scenario
+
+**Milestone:** M4 · **Mode:** HITL · **Triage:** `ready-for-human` · **Depends on:** DGR-053, DGR-060, DGR-061
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/062-certify-a-dynamic-real-10-stage-v4-scenario.md`, and evidence READMEs for dependencies (DGR-053, DGR-060, DGR-061) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Demonstrate that a large real route can be dynamically selected and usefully execute V4.
+
+- [ ] Run one real 10+-stage V4 certification scenario; stage count, quant, and split remain scenario metadata only.
+- [ ] Every selected stage proves real work, exact compatible identity, local state ownership, and bounded resources.
+- [ ] Record end-to-end and per-stage TTFT, prefill/decode, seam cost, queueing, memory, failures, and cleanup.
+- [ ] Inject at least one incompatible or degraded candidate and verify dynamic exclusion/reselection.
+- [ ] The scenario must meet its pre-locked usefulness threshold or remain failed evidence.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-063: Profile and optimize the critical seam
+
+**Milestone:** M4 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-057, DGR-061
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/063-profile-and-optimize-the-critical-seam.md`, and evidence READMEs for dependencies (DGR-057, DGR-061) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Optimize only the measured dominant compute, serialization, copy, or transport bottleneck.
+
+- [ ] Profile worker compute, tensor conversion, copies, protobuf framing, compression, relay/direct transport, queueing, and synchronization.
+- [ ] Select one dominant bottleneck from evidence and lock its before/after benchmark.
+- [ ] Implement one bounded optimization without weakening correctness or protocol identity.
+- [ ] Report whether the optimization changes TTFT, prefill, decode, throughput, or memory and preserve raw data.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-064: Add negotiated activation compression
+
+**Milestone:** M4 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-060, DGR-063
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/064-add-negotiated-activation-compression.md`, and evidence READMEs for dependencies (DGR-060, DGR-063) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Reduce V4 seam cost only when a certified compression recipe improves end-to-end performance acceptably.
+
+- [ ] Negotiate compression through recipe identity; unnegotiated or mismatched compression fails closed.
+- [ ] Preserve names, shapes, semantic axes, token-ID sideband, and checksums.
+- [ ] Measure quality drift, encode/decode cost, bytes, TTFT, and throughput against uncompressed boundaries.
+- [ ] Compression remains dark unless it meets pre-locked quality and speed thresholds.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-065: Define V4 MTP ownership and distributed state contract
+
+**Milestone:** M4 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-051, DGR-054, DGR-060
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/065-define-v4-mtp-ownership-and-distributed-state-contract.md`, and evidence READMEs for dependencies (DGR-051, DGR-054, DGR-060) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Lock MTP tensor, execution, boundary, acceptance/rejection, and session-state ownership before implementation while keeping MTP disabled for alpha.
+
+- [ ] Derive exact MTP tensor and execution ownership from the pinned V4 target and upstream llama.cpp graph, distinguishing main-layer, tail, and MTP responsibilities.
+- [ ] Define typed MTP inputs/outputs plus accepted-token, rejection, rollback/truncation, position, cache, and session/epoch lifecycle semantics.
+- [ ] Specify which MTP state remains shard-local and which typed boundary values cross a seam; prohibit WAN migration of KV or V4 auxiliary caches.
+- [ ] Keep every MTP recipe disabled and unroutable for alpha, with fail-closed capability negotiation and deterministic contract fixtures.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-066: Implement and benchmark V4 MTP
+
+**Milestone:** M4 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-054, DGR-060, DGR-064, DGR-065
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/066-implement-and-benchmark-v4-mtp.md`, and evidence READMEs for dependencies (DGR-054, DGR-060, DGR-064, DGR-065) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Implement the locked MTP contract around upstream llama.cpp before beta, without making MTP an alpha prerequisite.
+
+- [ ] Implement the exact DGR-065 MTP ownership and typed state contract against the pinned upstream V4 graph while preserving shard-local caches.
+- [ ] Pass whole-model versus ranged MTP correctness, accepted-token, rejection, rollback/truncation, and session-isolation tests.
+- [ ] Benchmark MTP-off versus MTP-on quality, accepted-token rate, TTFT, decode speed, seam bytes, and memory on the locked lane.
+- [ ] Distinguish implemented, certified, disabled, and unsupported MTP recipes in fail-closed capability advertisement.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-067: Certify the backend capability matrix
+
+**Milestone:** M4 · **Mode:** HITL · **Triage:** `ready-for-human` · **Depends on:** DGR-030, DGR-053, DGR-062, DGR-066
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/067-certify-the-backend-capability-matrix.md`, and evidence READMEs for dependencies (DGR-030, DGR-053, DGR-062, DGR-066) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Publish only backend/model/recipe lanes proven on actual CPU, CUDA, ROCm, Vulkan, or Metal hardware.
+
+- [ ] Maintain independent build and certification status for CPU, CUDA, ROCm, Vulkan, and Metal.
+- [ ] Each advertised lane includes real hardware/driver/runtime/model evidence for parity, concurrency, cancellation, cleanup, and useful speed.
+- [ ] Build success alone never makes a lane routable; unavailable hardware remains explicitly dark.
+- [ ] Tracker admission consumes signed/versioned certification records rather than backend-name allowlists.
+- [ ] Mixed-backend routes require exact compatibility evidence and fail closed otherwise.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-068: Package reproducible native worker releases
+
+**Milestone:** M5 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-030, DGR-054, DGR-067
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/068-package-reproducible-native-worker-releases.md`, and evidence READMEs for dependencies (DGR-030, DGR-054, DGR-067) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Produce installable worker packages that preserve exact source, patch, protocol, and certification identity.
+
+- [ ] Package worker binaries/configuration for supported host/backend combinations without bundling an unverified llama.cpp tree.
+- [ ] Embed protocol, engine, upstream pin, patch-stack, build-toolchain, and certification fingerprints.
+- [ ] Installation/startup refuses mismatched artifacts, runtime recipes, or unsupported hardware lanes.
+- [ ] Produce checksums, SBOM/license attribution, reproducible build instructions, and smoke tests.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-069: Prepare narrow upstream llama.cpp collaboration patches
+
+**Milestone:** M5 · **Mode:** HITL · **Triage:** `ready-for-human` · **Depends on:** DGR-028, DGR-035, DGR-038, DGR-051
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/069-prepare-narrow-upstream-llama-cpp-collaboration-patches.md`, and evidence READMEs for dependencies (DGR-028, DGR-035, DGR-038, DGR-051) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Reduce long-term patch burden through generic upstreamable hooks without asking llama.cpp to own Meshnet.
+
+- [ ] Separate generic range loading, boundary I/O, and filtered state hooks from project worker/protocol code.
+- [ ] Provide one scoped patch, focused test, and minimal reproducer per concern against the exact upstream pin.
+- [ ] Compare the proposal with prior-art evidence and current upstream V4 support/maturity.
+- [ ] Prepare human-ready design/outreach text; actual issue/PR submission remains a human action.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-070: Enforce the DeepSeek V4 Flash beta gate
+
+**Milestone:** M5 · **Mode:** HITL · **Triage:** `ready-for-human` · **Depends on:** DGR-057, DGR-059, DGR-060, DGR-062, DGR-064, DGR-066, DGR-067, DGR-068
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/070-enforce-the-deepseek-v4-flash-beta-gate.md`, and evidence READMEs for dependencies (DGR-057, DGR-059, DGR-060, DGR-062, DGR-064, DGR-066, DGR-067, DGR-068) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Promote beta only after concurrency, resilience, long-context, MTP, scale, packaging, and speed gates pass.
+
+- [ ] Evaluate all beta metrics against DGF-004 without changing thresholds after observing results.
+- [ ] Require V4 parity, batching/fairness, bounded backpressure, failure recovery, long-context correctness, MTP evidence, and dynamic 10+ stage evidence.
+- [ ] Publish the exact certified hardware/backend/recipe matrix; all other lanes remain dark.
+- [ ] Decision is `beta`, `targeted optimization`, or `stop/rollback`, with unresolved failures listed explicitly.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+### DGR-071: Establish upstream pin, patch, and certification maintenance
+
+**Milestone:** M5 · **Mode:** AFK · **Triage:** `ready-for-agent` · **Depends on:** DGR-069, DGR-070
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/071-establish-upstream-pin-patch-and-certification-maintenance.md`, and evidence READMEs for dependencies (DGR-069, DGR-070) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Keep beta reproducible and detect upstream/model/hardware drift before it reaches routable nodes.
+
+- [ ] Add a documented update procedure for llama.cpp pin, numbered patches, protocol/engine versions, V4 target revision, and certification records.
+- [ ] A candidate pin update must apply/build/test in isolation and cannot replace the production pin automatically.
+- [ ] Any changed graph, tensor inventory, boundary, cache/state layout, backend behavior, or performance invalidates affected certification.
+- [ ] Add scheduled model-free checks plus opt-in real-hardware recertification instructions and rollback procedure.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Non-goals
+
+- Replacing or redesigning Tracker routing/load-balancing, billing, relay, or provider policy.
+- Reimplementing DeepSeek V4 architecture graphs or kernels in Meshnet.
+- Hardcoding a quant, stage count, node count, split, architecture, or backend sequence.
+- WAN migration of KV or V4 auxiliary caches.
+- Advertising a compile-only or fixture-only hardware lane.
+- Making MTP an alpha dependency.

.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md

@@ -1,309 +1,57 @@
-# Ralph execution context: Performant Concurrent Distributed GGUF Runtime
+# Ralph context: Distributed GGUF Runtime
 
-Status: authoritative context for every fresh Ralph iteration
-Last updated: 2026-07-13
+> **Specification status:** planning artifacts only. No distributed GGUF runtime is implemented. DGR-017 cleanup is complete; no runtime implementation story has completion credit. `prd.json` is authoritative.
 
-## Mandatory startup sequence
+## Mandatory startup for every fresh story
 
-Before changing code, every Ralph agent must:
+1. Read this file and authoritative `prd.json` completely.
+2. Read the generated source issue named in the selected story description.
+3. Read every dependency evidence README; legacy DGR-001..016 evidence is provenance only.
+4. Read `docs/adr/0024-distributed-gguf-runtime.md`, root `CONTEXT.md`, `.claude/memory/MEMORY.md`, and relevant live source/tests.
+5. Inspect `git status`; preserve unrelated work. Never infer implementation from planning text or old pass states.
+6. If blocked or oversized, keep `passes: false` and write an honest `BLOCKED.md`/`DECOMPOSITION.md`; never weaken criteria or fabricate evidence.
 
-1. Read this file completely.
-2. Read the selected issue under `.scratch/distributed-gguf-runtime/issues/`.
-3. Read `docs/adr/0024-distributed-gguf-runtime.md` and the relevant part of `architecture.md`.
-4. Read `.claude/memory/MEMORY.md` and root `CONTEXT.md` for current project vocabulary and constraints.
-5. Inspect the current implementation and tests; do not assume historical scratch text describes live code.
-6. Read the evidence/handoff directories for every declared dependency.
-7. Inspect `git status` and preserve all pre-existing working-tree changes.
+## Locked scope
 
-A fresh Ralph iteration has no conversational memory. These files are the context contract.
+- Existing Meshnet Tracker routing, load balancing, billing, telemetry, relay, and provider semantics are backend-agnostic and are **not redesigned**. GGUF contributes exact compatibility, range/capacity, queue/load, seam-cost, health/reliability, and certification inputs only.
+- The data plane is a standalone project-owned C++ Shard worker with gRPC/Protobuf and a project-owned `ShardEngine` boundary.
+- llama.cpp is fetched at one exact commit into an ignored workspace from an in-repo manifest, then a numbered minimal patch stack is applied. There is no submodule, vendored tree, or permanent-fork dependency.
+- llama.cpp owns DeepSeek V4 graphs, mHC, MoE, attention, hash routing, and kernels. Meshnet adds only range-ownership hooks, typed boundary/local-state adapters, worker integration, and parity/certification.
+- Quantization and placement are dynamic recipe inputs. The 2–4 and 10+ stage layouts are certification scenarios, never product constants.
+- Per-shard Hot KV and V4 CSA/HCA/SWA/indexer/compressor state remain local and keyed by route session/epoch. The WAN seam carries the typed mHC 4×4096 residual boundary, positions, token-ID sideband where required, and schema/cache expectations—not per-layer caches.
+- Route changes use cache miss plus re-prefill/restart. There is no WAN KV or V4 auxiliary-cache migration.
+- CPU/CUDA/ROCm/Vulkan/Metal compile lanes are planned; only exact real-hardware-certified backend/model/recipe lanes may be advertised.
+- Alpha requires correctness and the pre-locked useful-speed gate. MTP is reserved and off for alpha; its ownership contract, implementation, and benchmark are required before beta.
 
-## Story sizing and interruption rule
+## Target identities
 
-Each story is intended to fit one focused Ralph context. Before implementation, estimate whether every acceptance criterion can be completed and verified in the current iteration.
+- DeepSeek V4 official target SHA: `60d8d70770c6776ff598c94bb586a859a38244f1`.
+- llama.cpp V4 support lineage began at PR 24162 / merge `8c146a8366304c871efc26057cc90370ccf58dad`; DGR-027 later pins one exact validated current commit.
+- V4 scope: 43 main layers plus MTP; mHC 4×4096 boundary; 256 routed + 1 shared experts with six routed active; token IDs required for the first three hash-routed layers.
+- Exact split-GGUF artifacts are provisioned to mounted-drive storage with a complete hashed manifest and resumable verification; no model artifact may be placed under `/home`.
 
-If the story is too large, an external dependency is unavailable, or the context/provider limit prevents completion:
+## Control/data-plane contract
 
-- Do not weaken criteria.
-- Do not mark the issue done or set `passes: true`.
-- Avoid leaving an unverified cross-cutting partial implementation when a smaller safe spike is possible.
-- Write `evidence/<TASK-ID>/DECOMPOSITION.md` or `BLOCKED.md` with the exact blocker, current verified state, proposed child stories, dependency graph and rollback/continuation instructions.
-- Stop for supervised review.
+Meshnet continues to own registration, coverage, existing route selection/load balancing, route epochs/sessions, direct/relay behavior, capability admission, cancellation, telemetry, billing, validation, and attribution. The GGUF adapter exposes measured inputs to those existing mechanisms. Direct seams use long-lived gRPC streams; relay seams carry byte-identical protobuf frames opaquely.
 
-If interrupted after code changes, record every changed file, command result and unresolved invariant so the next fresh loop can verify rather than guess.
+The project-owned `ShardEngine` hides llama.cpp internals. A worker loads one exact artifact/recipe/range identity. Default tests use fake/tiny fixtures. Real runs are opt-in, preserve raw metrics, and never download models under `/home`.
 
-## Product objective
+## Gitea issue synchronization
 
-Build performant, concurrent distributed inference that combines consumer machines to serve top open models that exceed one node's RAM/VRAM.
+Gitea is a projection of `prd.json`, never a competing source of truth. Before and after every supervised Ralph run, invoke:
 
-A distributed demo is not success. The product must provide:
-
-- Useful measured prefill and decode speed.
-- Multiple concurrent Route Sessions.
-- No KV/token cross-talk.
-- Bounded memory, queues, cancellation and failures.
-- Real execution on every participating node.
-- A model-fit or performance advantage over the current Transformers/safetensors route.
-
-## Critical-path architecture
-
-```text
-Existing Meshnet control plane
-        |
-Versioned Protobuf over gRPC/HTTP2
-        |
-Project-owned standalone C++ Shard worker
-        |
-Small exact-commit llama.cpp patch stack
+```bash
+python3 scripts/ralph_gitea_sync.py sync
 ```
 
-Meshnet remains the only control plane and owns:
+For a complete Ralph invocation with automatic state reconciliation, use:
 
-- Tracker registration, Coverage Map, route selection and route epochs.
-- Route Sessions and Activation Seams.
-- Direct/relay routing.
-- Capability admission.
-- Cancellation, Generation Telemetry and backpressure.
-- Billing, validation and per-node work attribution.
-
-Do not introduce another scheduler/control plane from vLLM, Nakshatra, prima.cpp, llama-gguf, GPUStack or another project.
-
-## Runtime decisions that are not open
-
-1. Public-network Shards are contiguous transformer layer ranges.
-2. llama.cpp/GGML is the native GGUF execution substrate.
-3. The project owns a small standalone worker and a narrow pinned llama.cpp patch stack.
-4. The native Shard protocol is Protocol Buffers over gRPC/HTTP2.
-5. One long-lived bidirectional stream serves one Route Session Activation Seam.
-6. The public activation boundary is a versioned named-tensor bundle.
-7. Hot KV State remains local to the node serving the Shard.
-8. `(Route Session ID, route epoch)` maps to an isolated llama sequence or bounded context.
-9. Concurrency uses continuous batching of compatible active sessions inside each node.
-10. Transformers/safetensors remains the correctness and performance baseline.
-11. vLLM may be an optional complete managed provider and concept donor; it is not forked into public Shards.
-12. Tensor/expert collectives are deferred to a trusted composite provider, not public WAN routes.
-13. Unsupported architectures/backends remain registered-but-dark until real certification passes.
-14. Alpha failure retries from token zero; unverified KV is never migrated silently.
-15. Model artifacts must remain on mounted-drive storage and never under `/home`.
-
-Changing one of these requires an explicit ADR update and human review, not an incidental story implementation.
-
-## Performance discipline
-
-GGUF performance is a hypothesis. Never write “GGUF is faster” without measurements.
-
-DGR-001 locks controlled benchmark lanes and thresholds. DGR-014 enforces the final distributed comparison.
-
-Always distinguish:
-
-- Weight quantization from activation/compute/KV dtype.
-- Runtime/kernel gains from quantization/model-fit gains.
-- Single-request latency from aggregate concurrency throughput.
-- Synthetic unit coverage from real distributed acceptance.
-
-Required metrics where applicable:
-
-```text
-TTFT
-prefill tokens/sec
-decode tokens/sec
-aggregate throughput
-p50/p95 latency
-seam bytes and latency
-queue and batch occupancy
-RSS and VRAM
-KV pressure
-output-quality drift
-failures and cleanup
+```bash
+scripts/ralph-gitea-run.sh ralph-tui run --prd .scratch/distributed-gguf-runtime/prd.json --agent claude --model sonnet --iterations 1 --no-tui --no-setup --direct-merge --no-sandbox
 ```
 
-Do not weaken or move performance thresholds after seeing implementation results.
+The sync creates/reconciles one Gitea issue per `DGR-*` story, creates missing labels/milestones, closes issues whose `passes` is true, marks the selected next eligible story `status:in-progress`, and marks blocked stories `status:blocked`. `gitea-issues.json` is a derived mapping only.
 
-## Transport discipline
+## Evidence and completion
 
-Do not invent a raw TCP protocol, new WebSocket protocol, QUIC layer or bespoke binary control format.
-
-The `.proto` schema is the semantic contract. Direct transport uses gRPC. Existing relay infrastructure may carry the same serialized protobuf frames as opaque binary.
-
-Protocol requirements:
-
-- Schema/version negotiation.
-- Request/work ID.
-- Route Session ID and route epoch.
-- Exact Model Artifact/runtime recipe fingerprint.
-- Shard range and effective overlap-safe start.
-- Prefill/decode/release/cancel phases.
-- Position/token range and idempotency step.
-- Named tensors with shape, dtype, byte order and bounded fragments.
-- Compression/checksum.
-- Cache expectation/result.
-- Deadlines, cancellation, flow control and structured status.
-
-Avoid per-token channel creation and unbounded unary payloads. Generated code and build tooling must be reproducible; do not require manual copying.
-
-## Native runtime discipline
-
-Reuse llama.cpp for GGUF, mmap, kernels, architecture graphs, tokenizer, KV, sequences and heterogeneous backends.
-
-The project patch stack is limited to:
-
-- Range-aware tensor registration/loading.
-- Endpoint-specific embedding/final head ownership.
-- Architecture-defined intermediate input/output.
-- Intermediate output before final norm/head.
-- Layer-filtered KV and session mapping.
-
-Do not place Meshnet routing, transport, billing or authentication inside llama.cpp. Keep patches numbered, scoped, pinned and upstreamable.
-
-Dense Llama-family is first. Qwen3/Qwen3-MoE is a separate adapter after the dense release gate. Do not generalize through unchecked tensor-name substitutions.
-
-## Existing code seams to inspect first
-
-- `packages/node/meshnet_node/model_backend.py` — backend abstraction.
-- `packages/node/meshnet_node/torch_server.py` — reference ranged execution and session behavior.
-- `packages/node/meshnet_node/activation_compression.py` — current activation framing/compression.
-- `packages/node/meshnet_node/route_session_benchmark.py` — existing benchmark infrastructure.
-- `packages/tracker/meshnet_tracker/server.py` — registration, route and proxy behavior.
-- `packages/tracker/meshnet_tracker/capability.py` — fail-closed capability admission.
-- `tests/test_real_model_backend.py` — real backend coverage.
-- `tests/test_tracker_routing.py` — route/session behavior.
-- `tests/test_tracker_capability_admission.py` — recipe admission.
-- `tests/test_route_session_benchmark.py` and `tests/test_manual_route_benchmark.py` — benchmark patterns.
-- `docs/adr/0008-binary-activation-wire-format.md` — existing wire compatibility.
-- `docs/adr/0012-start-layer-overlapping-shards.md` — effective start semantics.
-- `docs/adr/0022-sharded-per-node-kv-cache.md` — Hot KV State contract.
-- `docs/adr/0023-model-agnostic-node-capability-admission.md` — certification/admission.
-
-Do not edit generated `build/`, `__pycache__`, egg-info, Ralph logs or unrelated scratch features.
-
-## Planned source layout
-
-Use these paths unless current code inspection proves a better project-consistent location. If changed, document the reason in task evidence.
-
-```text
-packages/node/native/
-  proto/shard_runtime.proto
-  cmake/
-  llama/
-    UPSTREAM_COMMIT
-    patches/
-  gguf_worker/
-  tests/
-
-packages/node/meshnet_node/
-  native_protocol/
-  gguf_backend.py
-  runtime_recipe.py
-
-.scratch/distributed-gguf-runtime/evidence/<TASK-ID>/
-  README.md
-  commands.txt
-  results.json or other machine-readable evidence
-```
-
-Generated protobuf/C++ build outputs belong in build directories unless packaging explicitly requires checked-in generated Python modules. The story must document the generation command and version.
-
-## Story output map
-
-| Story | Required durable outputs |
-|---|---|
-| DGR-001 | benchmark harness/tests; `evidence/DGR-001/performance-contract.json`; raw/summary benchmark evidence |
-| DGR-002 | `packages/node/native/proto/shard_runtime.proto`; reproducible Python/C++ generation/build wiring; protocol round-trip/compatibility tests; `evidence/DGR-002/` |
-| DGR-003 | exact runtime-recipe/fingerprint implementation and admission tests; `evidence/DGR-003/` |
-| DGR-004 | exact upstream pin, numbered patch series, reproducible fetch/apply/build smoke; `evidence/DGR-004/` |
-| DGR-005 | dense-Llama range ownership loader and memory evidence; `evidence/DGR-005/` |
-| DGR-006 | architecture boundary adapter/parity tests and results; `evidence/DGR-006/` |
-| DGR-007 | concurrent session/KV manager, isolation/cleanup tests; `evidence/DGR-007/` |
-| DGR-008 | standalone C++ gRPC worker, fake-model integration tests, lifecycle evidence; `evidence/DGR-008/` |
-| DGR-009 | Meshnet backend/registration/relay integration and tests; `evidence/DGR-009/` |
-| DGR-010 | real local two-process commands, raw metrics and parity report; `evidence/DGR-010/` |
-| DGR-011 | two-machine configuration, commands, hardware/network manifest and raw results; `evidence/DGR-011/` |
-| DGR-012 | continuous scheduler/admission implementation and 1/2/4/8 concurrency report; `evidence/DGR-012/` |
-| DGR-013 | failure/cancel/restart test matrix and resource-cleanup evidence; `evidence/DGR-013/` |
-| DGR-014 | immutable final comparison against DGR-001 thresholds and ship/stop recommendation; `evidence/DGR-014/` |
-| DGR-015 | Qwen3-family adapter, architecture-specific parity/admission/performance evidence; `evidence/DGR-015/` |
-| DGR-016 | narrow upstream patches/tests, design note and human-ready outreach package; `evidence/DGR-016/` |
-
-## Dependency handoff rule
-
-For every dependency listed by Ralph:
-
-1. Confirm its `passes` state in `prd.json`.
-2. Read `.scratch/distributed-gguf-runtime/evidence/<DEPENDENCY-ID>/README.md`.
-3. Verify referenced source paths and commands still exist.
-4. Do not repeat completed work unless verification exposes a concrete defect.
-5. If dependency evidence is missing or contradictory, stop and repair the dependency instead of guessing.
-
-## Testing and hardware rules
-
-Default tests must be deterministic, GPU-free, model-download-free and API-credit-free.
-
-Real model tests require:
-
-```text
-MESHNET_ENABLE_REAL_INFERENCE_TESTS=1
-```
-
-On this machine:
-
-- Use `.venv-rocm` for real Radeon 8060S ROCm execution.
-- The default Python 3.14 `.venv` is unsuitable for real ROCm inference.
-- Resolve model storage through the machine-specific `.env.<hostname>` configuration.
-- Never download model artifacts under `/home`.
-- Real acceptance must exercise actual Tracker-routed CPU/GPU computation; synthetic workers are only unit tests.
-
-Record exact:
-
-- Model/revision and Artifact hash.
-- Quantization and runtime recipe.
-- Host/hardware/backend/driver.
-- Commands and environment names without secrets.
-- Raw output and metrics.
-- Whether the evidence is synthetic, local-real, or multi-machine-real.
-
-## Worktree and commit discipline
-
-This repository may contain pre-existing changes from research or another feature.
-
-- Inspect `git status` before editing.
-- Never reset, checkout over, stash, delete or reformat unrelated changes.
-- Stage only files belonging to the selected story.
-- Exclude `.ralph-tui`, iteration logs, caches, generated builds, FUSE artifacts and unrelated scratch work.
-- Keep one scoped commit per completed story when the supervising loop requests commits.
-- Do not modify `passes` for another story.
-
-## Mandatory finish/handoff sequence
-
-Before emitting `<promise>COMPLETE</promise>`:
-
-1. Verify every acceptance criterion with real command output or file evidence.
-2. Run story-specific gates and repository quality gates.
-3. Write `.scratch/distributed-gguf-runtime/evidence/<TASK-ID>/README.md` containing:
-   - Summary of changes.
-   - Exact files changed.
-   - Commands run and their real results.
-   - Performance/correctness evidence.
-   - Known limitations and deferred work.
-   - Compatibility or migration notes.
-   - Clear handoff for dependent stories.
-4. Save machine-readable evidence beside it when the story produces metrics or schemas.
-5. Update the source issue status to `done` only after all gates pass.
-6. Preserve failures honestly. Never fabricate model, benchmark, test or hardware output.
-
-## Authoritative references
-
-Active decisions:
-
-- `.scratch/distributed-gguf-runtime/README.md`
-- `.scratch/distributed-gguf-runtime/implementation-strategy.md`
-- `.scratch/distributed-gguf-runtime/architecture.md`
-- `docs/adr/0024-distributed-gguf-runtime.md`
-- `.scratch/distributed-gguf-runtime/PRD.md`
-- `.scratch/distributed-gguf-runtime/prd.json`
-
-Source research:
-
-- `docs/research/distributed-gguf-landscape.md`
-- `docs/research/distributed-gguf-github-followup.md`
-- `docs/research/vllm-distributed-gguf-assessment.md`
-
-If historical notes conflict with these files, the active decisions above win.
+Each story writes `/run/media/popov/d/DEV/repos/d-popov.com/AI/.claude/worktrees/distributed-gguf-runtime/.scratch/distributed-gguf-runtime/evidence/<DGR-ID>/README.md` with exact files, commands/results, limitations, identities, and dependent-story handoff. Only `prd.json` may record `passes`; DGR-017 and DGR-018 are complete and DGR-019 onward remain false. Generated Markdown and Gitea issues cannot override it. One scoped commit per story is expected during future execution.

.scratch/distributed-gguf-runtime/README.md

@@ -1,46 +1,32 @@
-# Performant concurrent distributed GGUF runtime
+# Distributed GGUF Runtime planning workspace
 
-Status: active benchmark-gated implementation program.
+> **Specification status:** planning artifacts only. No distributed GGUF runtime is implemented. DGR-017 cleanup is complete; no runtime implementation story has completion credit. `prd.json` is authoritative.
 
-## Objective
 
-Serve top open models across consumer machines with useful performance and concurrent Route Sessions while keeping the runtime lean.
+## Locked scope
 
-## Critical path
+- Existing Meshnet Tracker routing, load balancing, billing, telemetry, relay, and provider semantics are backend-agnostic and are **not redesigned**. GGUF contributes exact compatibility, range/capacity, queue/load, seam-cost, health/reliability, and certification inputs only.
+- The data plane is a standalone project-owned C++ Shard worker with gRPC/Protobuf and a project-owned `ShardEngine` boundary.
+- llama.cpp is fetched at one exact commit into an ignored workspace from an in-repo manifest, then a numbered minimal patch stack is applied. There is no submodule, vendored tree, or permanent-fork dependency.
+- llama.cpp owns DeepSeek V4 graphs, mHC, MoE, attention, hash routing, and kernels. Meshnet adds only range-ownership hooks, typed boundary/local-state adapters, worker integration, and parity/certification.
+- Quantization and placement are dynamic recipe inputs. The 2–4 and 10+ stage layouts are certification scenarios, never product constants.
+- Per-shard Hot KV and V4 CSA/HCA/SWA/indexer/compressor state remain local and keyed by route session/epoch. The WAN seam carries the typed mHC 4×4096 residual boundary, positions, token-ID sideband where required, and schema/cache expectations—not per-layer caches.
+- Route changes use cache miss plus re-prefill/restart. There is no WAN KV or V4 auxiliary-cache migration.
+- CPU/CUDA/ROCm/Vulkan/Metal compile lanes are planned; only exact real-hardware-certified backend/model/recipe lanes may be advertised.
+- Alpha requires correctness and the pre-locked useful-speed gate. MTP is reserved and off for alpha; its ownership contract, implementation, and benchmark are required before beta.
 
-```text
-Meshnet control plane
-  -> versioned gRPC/Protobuf Shard protocol
-  -> project-owned standalone C++ worker
-  -> small pinned llama.cpp patch stack
-```
+## Target identities
 
-Transformers/safetensors remains the correctness baseline. vLLM remains an optional complete managed provider and a design donor; it is not forked into the public mesh.
+- DeepSeek V4 official target SHA: `60d8d70770c6776ff598c94bb586a859a38244f1`.
+- llama.cpp V4 support lineage began at PR 24162 / merge `8c146a8366304c871efc26057cc90370ccf58dad`; DGR-027 later pins one exact validated current commit.
+- V4 scope: 43 main layers plus MTP; mHC 4×4096 boundary; 256 routed + 1 shared experts with six routed active; token IDs required for the first three hash-routed layers.
+- Exact split-GGUF artifacts are provisioned to mounted-drive storage with a complete hashed manifest and resumable verification; no model artifact may be placed under `/home`.
 
-## Planning artifacts
+## Navigation
 
-- **[Mandatory Ralph context](RALPH-CONTEXT.md)** — read first in every fresh iteration
-- [Task evidence contract](evidence/README.md)
-- [Implementation strategy](implementation-strategy.md)
-- [Current architecture](architecture.md)
-- [PRD](PRD.md)
-- [Ralph backlog](prd.json)
-- [ADR-0024](../../docs/adr/0024-distributed-gguf-runtime.md)
-- [Milestones](milestones.md)
-- [Issues](issues/)
-- [Distributed GGUF research](../../docs/research/distributed-gguf-landscape.md)
-- [GitHub follow-up](../../docs/research/distributed-gguf-github-followup.md)
-- [vLLM assessment](../../docs/research/vllm-distributed-gguf-assessment.md)
-
-## Ralph execution
-
-Use supervised one-story iterations for this high-risk runtime:
-
-```bash
-ralph-tui run \
-  --prd .scratch/distributed-gguf-runtime/prd.json \
-  --agent claude --model opus \
-  --iterations 1 --no-tui --no-setup --verify
-```
-
-Inspect the diff, run the story gates, and commit one verified story before the next iteration. Real-model stories require the explicit environment gate and mounted-drive model storage.
+- [`prd.json`](prd.json) — sole authoritative 55-story backlog, DGR-017..071.
+- [`PRD.md`](PRD.md) — human-readable projection of goals, gates, and all stories.
+- [`RALPH-CONTEXT.md`](RALPH-CONTEXT.md) — mandatory fresh-session context.
+- [`architecture.md`](architecture.md), [`implementation-strategy.md`](implementation-strategy.md), [`milestones.md`](milestones.md) — design and execution sequence.
+- [`issues/`](issues/) — generated story specs; files 01..16 are retained legacy artifacts pending DGR-017.
+- [`evidence/`](evidence/) — provenance and future per-story handoffs.

.scratch/distributed-gguf-runtime/architecture.md

@@ -1,259 +1,45 @@
-# Performant Concurrent Distributed GGUF Architecture
+# Distributed GGUF Runtime architecture
 
-Status: current target architecture
-Last updated: 2026-07-13
+> **Specification status:** planning artifacts only. No distributed GGUF runtime is implemented. DGR-017 cleanup is complete; no runtime implementation story has completion credit. `prd.json` is authoritative.
 
-## Product invariant
 
-The system exists to serve high-quality models that exceed one consumer node's memory while retaining useful interactive speed and aggregate concurrency. A feature that only produces a distributed demo but is slower, globally serialized, or impossible to operate on consumer hardware is not complete.
+## Locked scope
 
-## Existing control plane
+- Existing Meshnet Tracker routing, load balancing, billing, telemetry, relay, and provider semantics are backend-agnostic and are **not redesigned**. GGUF contributes exact compatibility, range/capacity, queue/load, seam-cost, health/reliability, and certification inputs only.
+- The data plane is a standalone project-owned C++ Shard worker with gRPC/Protobuf and a project-owned `ShardEngine` boundary.
+- llama.cpp is fetched at one exact commit into an ignored workspace from an in-repo manifest, then a numbered minimal patch stack is applied. There is no submodule, vendored tree, or permanent-fork dependency.
+- llama.cpp owns DeepSeek V4 graphs, mHC, MoE, attention, hash routing, and kernels. Meshnet adds only range-ownership hooks, typed boundary/local-state adapters, worker integration, and parity/certification.
+- Quantization and placement are dynamic recipe inputs. The 2–4 and 10+ stage layouts are certification scenarios, never product constants.
+- Per-shard Hot KV and V4 CSA/HCA/SWA/indexer/compressor state remain local and keyed by route session/epoch. The WAN seam carries the typed mHC 4×4096 residual boundary, positions, token-ID sideband where required, and schema/cache expectations—not per-layer caches.
+- Route changes use cache miss plus re-prefill/restart. There is no WAN KV or V4 auxiliary-cache migration.
+- CPU/CUDA/ROCm/Vulkan/Metal compile lanes are planned; only exact real-hardware-certified backend/model/recipe lanes may be advertised.
+- Alpha requires correctness and the pre-locked useful-speed gate. MTP is reserved and off for alpha; its ownership contract, implementation, and benchmark are required before beta.
 
-Meshnet remains the only public control plane:
+## Target identities
 
-- Tracker registration, Coverage Map, route scoring and assignment.
-- Contiguous Shards and overlap-safe effective starts.
-- Stable Route Sessions and route epochs.
-- Local per-Shard Hot KV State in the reference backend.
-- Direct/relay transport, cancellation and backpressure.
-- Generation Telemetry, billing, validation and per-node attribution.
-- Model-agnostic capability admission.
+- DeepSeek V4 official target SHA: `60d8d70770c6776ff598c94bb586a859a38244f1`.
+- llama.cpp V4 support lineage began at PR 24162 / merge `8c146a8366304c871efc26057cc90370ccf58dad`; DGR-027 later pins one exact validated current commit.
+- V4 scope: 43 main layers plus MTP; mHC 4×4096 boundary; 256 routed + 1 shared experts with six routed active; token IDs required for the first three hash-routed layers.
+- Exact split-GGUF artifacts are provisioned to mounted-drive storage with a complete hashed manifest and resumable verification; no model artifact may be placed under `/home`.
 
-No external engine replaces these responsibilities.
-
-## Runtime topology
+## Topology
 
 ```text
-OpenAI-compatible client
-        |
-Gateway / Tracker Node
-        |
-ordered Inference Route
-        |
-        +-- head Shard: tokenizer/embedding + early layers
-        |       local weights and Hot KV State
-        |
-        +-- middle Shard(s): architecture boundary + owned layers
-        |       local weights and Hot KV State
-        |
-        +-- tail Shard: final layers + norm/head/sampling
-                local weights and Hot KV State
+existing Meshnet Tracker/control plane
+  -> existing backend-agnostic route/load-balancing decision
+  -> direct gRPC or existing opaque relay
+  -> project-owned standalone C++ Shard worker
+  -> project-owned ShardEngine
+  -> pinned upstream llama.cpp + numbered range/boundary/state hook patches
+  -> GGUF mmap, upstream V4 graph/kernels, local per-shard state
 ```
 
-Weights never move in the per-request hot path. Every node opens and verifies its local Model Artifact before becoming routable.
+A route is ordered contiguous half-open ranges. Head owns token embedding; tail owns final norm/head/sampling. Compatibility fingerprints bind source/split hashes, tokenizer, architecture adapter, typed boundary, runtime pin/patches, backend, quant, activation/compute/KV layout, range, and certification.
 
-## Primary execution substrate
+## V4 boundary and state
 
-```text
-project-owned C++ Shard worker
-        |
-small exact-commit llama.cpp patch stack
-        |
-GGUF mmap, quantized kernels, architecture graphs,
-KV/sequence operations, CPU/CUDA/HIP/Vulkan/Metal backends
-```
+The inter-stage boundary is semantic and versioned: mHC 4×4096 residual, positions, token IDs only where the first three hash-routed layers require them, and cache/schema expectations. CSA/HCA/SWA/indexer/compressor/KV state belongs to upstream layer execution on the owning worker and is isolated by `(route_session_id, route_epoch)`. On loss, return cache miss and re-prefill/restart. Never serialize those caches into the WAN bundle.
 
-The patch stack adds only the missing local execution seam:
+## Concurrency, failure, and admission
 
-1. Range-aware tensor registration/loading.
-2. Endpoint-specific embedding and final head ownership.
-3. Architecture-defined intermediate input.
-4. Architecture-defined pre-tail boundary output.
-5. Layer-filtered KV and external session mapping.
-
-The worker owns protocol translation and process lifecycle. llama.cpp never receives Tracker, relay, billing or volunteer-network code.
-
-## Shard data plane
-
-Use Protocol Buffers and gRPC over HTTP/2.
-
-### Service shape
-
-- Unary capability and health.
-- Bidirectional Route Session stream.
-- Explicit release and cancellation.
-- Metrics suitable for capability admission and route scoring.
-
-### Session stream
-
-One long-lived stream represents one Route Session Activation Seam. It amortizes connection setup and inherits HTTP/2 flow control. Every message carries enough identity to reject stale or incompatible work.
-
-```text
-schema version
-request/work id
-Route Session id
-route epoch
-Model Artifact hash
-runtime recipe fingerprint
-Shard begin/end and effective start
-prefill/decode/release/cancel phase
-position and token range
-idempotency step id
-cache expectation/result
-named tensor bundle
-compression/checksum
-```
-
-Prefill tensors are split into bounded ordered frames. Decode messages carry one-step architecture boundary bundles and remain small.
-
-Direct nodes use gRPC. Nodes requiring the existing relay carry the same protobuf frames as opaque binary through the relay session. This preserves one semantic protocol instead of maintaining separate direct and relay payload contracts.
-
-## Architecture boundary
-
-The public boundary is a versioned named-tensor bundle:
-
-```text
-bundle schema/version
-architecture adapter and boundary point
-named tensors
-per-tensor shape, dtype and byte order
-payload fragments
-compression/checksum
-```
-
-Dense Llama may use one residual tensor. Other adapters may require more. vLLM's Llama and Qwen3-MoE PP paths demonstrate a boundary with both `hidden_states` and `residual`; therefore the generic protocol must not assume one anonymous tensor.
-
-Only the head owns token embedding. Only the tail owns final normalization, LM head and sampling. Middle Shards exchange the architecture-defined pre-tail boundary, not final normalized embeddings.
-
-## Hot KV State and concurrency
-
-```text
-(Route Session id, route epoch)
-       -> local llama sequence or bounded context
-       -> KV for owned layers only
-       -> lease, memory accounting and lifecycle
-```
-
-Required operations:
-
-- Prefill append.
-- Decode append.
-- Truncate after rejected speculative positions if later enabled.
-- Explicit release.
-- TTL/LRU eviction.
-- Cache-miss response.
-- Stale-epoch rejection.
-
-A node must not clear global KV on a new stream or serialize all requests behind one logical serving sequence.
-
-## Continuous batching
-
-Autoregressive dependencies remain sequential inside one Route Session. Aggregate throughput comes from batching compatible decode steps across active sessions:
-
-```text
-time 0: session A token 1 + session B token 8 + session C token 3
-          -> one llama batch for this Shard
-
-time 1: next ready positions from active sessions
-          -> next llama batch
-```
-
-The node scheduler:
-
-- Admits work against weight, KV, scratch and queue budgets.
-- Keeps per-session token positions and outputs separate.
-- Prevents long prefill from starving decode.
-- Applies bounded backpressure.
-- Reports active sessions, queue depth, batch occupancy, KV pressure and throughput.
-
-The initial deterministic gate is four concurrent sessions on a small model without cross-talk. Hardware-specific limits are measured and advertised through capability admission.
-
-## Parallelism boundaries
-
-| Mechanism | First-runtime use |
-|---|---|
-| Layer/pipeline parallelism | Public Inference Route across contiguous Shards |
-| Continuous batching | Inside every node across active Route Sessions |
-| Data parallelism | Multiple complete routes for independent requests |
-| Tensor parallelism | Deferred to a trusted composite node/managed cluster |
-| Expert parallelism | Deferred to a trusted composite node/managed cluster |
-| Disaggregated prefill | Deferred until core route performance passes |
-| Speculative decoding | Deferred optimization |
-
-Public WAN tensor/expert collectives are rejected for the first runtime because their per-layer communication and static rank assumptions conflict with heterogeneous volunteer nodes.
-
-## Optional providers
-
-### Transformers/safetensors
-
-Remains:
-
-- Correctness/reference backend.
-- Fallback for unsupported architectures.
-- Baseline for performance and output quality.
-
-### vLLM
-
-May run unmodified as a complete model or managed TP/PP/EP cluster represented as one logical provider. Its internal ranks are not independently routed or rewarded.
-
-Borrow only concepts such as named bundles, continuous batching, typed compatibility fingerprints, explicit transfer lifecycle and load telemetry.
-
-### Whole-model llama.cpp
-
-Provides a local proxy backend, correctness oracle and performance baseline. It is not the native distributed milestone.
-
-## Artifact and recipe compatibility
-
-A routable recipe identifies separately:
-
-- Source Model Artifact hash and optional derivative/slice hash.
-- Architecture and adapter version.
-- Tokenizer revision and vocabulary.
-- Weight quantization.
-- Activation interchange dtype/schema.
-- Backend compute dtype and backend implementation.
-- KV dtype/layout.
-- RoPE/context parameters.
-- llama.cpp commit and project patch version.
-- Shard range and endpoint ownership.
-
-Compatibility fails closed. Similar quantization labels or model names are not enough.
-
-## Admission and failure
-
-A recipe becomes routable only after a real local and distributed forward passes. Synthetic tests remain unit coverage.
-
-Alpha failure behavior:
-
-- Deadline or node loss cancels the Route Session.
-- Every node releases KV and queued buffers.
-- Uncertain mutations are not replayed silently.
-- Retry starts from token zero on a newly compatible route.
-- No cross-node KV import is trusted until a later signed/compatible snapshot protocol exists.
-
-## Performance release contract
-
-Before native development proceeds, compare the current Transformers/safetensors backend with whole-model llama.cpp under controlled model/hardware/quality lanes.
-
-Final release compares distributed GGUF with distributed safetensors using thresholds locked before seeing final results.
-
-Required measurements:
-
-- TTFT.
-- Prefill and decode tokens/sec.
-- Aggregate concurrency throughput.
-- p50/p95 latency.
-- Seam bytes and latency.
-- Queue/batch occupancy.
-- RSS, VRAM and KV pressure.
-- Output-quality drift.
-- Cancellation/failure cleanup.
-
-The GGUF path ships only if it is faster at acceptable quality or enables a larger otherwise-unroutable model at useful measured speed.
-
-## Implementation sequence
-
-1. Lock benchmark/performance contract.
-2. Define gRPC/protobuf and exact recipe identity.
-3. Pin llama.cpp and create the minimal patch stack.
-4. Implement dense-Llama range loading and boundary parity.
-5. Implement concurrent local KV.
-6. Build and integrate the standalone worker.
-7. Pass local two-process real-model acceptance.
-8. Pass real heterogeneous two-machine acceptance.
-9. Add continuous batching and failure hardening.
-10. Enforce the GGUF-versus-safetensors release gate.
-11. Add Qwen3/Qwen3-MoE as a separately certified adapter.
-12. Prepare narrow upstream collaboration patches/tests.
-
-See [the Ralph backlog](prd.json) and [implementation strategy](implementation-strategy.md).
+Compatible sessions may be continuously batched within a worker while retaining isolated positions/state. Admission bounds weights, local state/KV, scratch, fragments, and queues. Uncertain cross-route mutation is not replayed. Registration can show an uncertified lane, but existing admission keeps it unroutable until signed/versioned real-hardware evidence exists.

.scratch/distributed-gguf-runtime/decision-framework.md

@@ -1,270 +1,40 @@
-# Distributed GGUF Decision Framework
-
-> **Superseded for active implementation decisions.** The grill was resolved on 2026-07-13. Use [implementation-strategy.md](implementation-strategy.md), [architecture.md](architecture.md), [ADR-0024](../../docs/adr/0024-distributed-gguf-runtime.md), and [prd.json](prd.json). This file remains as historical decision rationale.
-
-This framework is for grilling open decisions. It keeps decisions tied to project vocabulary and implementation gates instead of vague "distributed inference" language.
-
-## Core Vocabulary
-
-Use the existing domain terms this way:
-
-- **Shard**: contiguous transformer layer range. This is the compute, routing, cache, and reward unit.
-- **Shard Swarm**: storage/download group for artifacts needed by a shard.
-- **Inference Route**: ordered node sequence that covers all layers for one request.
-- **Route Session**: one active request bound to one inference route and stable session id.
-- **Hot KV State**: live per-shard cache held by the route node during a route session.
-- **Prefix Snapshot**: persisted route-session state used for reuse or failover, not the hot decode path.
-- **Artifact Manifest**: canonical mapping from model artifacts to semantic model parts and runtime support.
-- **Generation Telemetry**: realtime progress for a route session, including phase and tokens/sec, independent of whether token deltas are streamed.
-
-## The Five Planes
-
-### 1. Control Plane
-
-Owner: Tracker.
-
-Responsibilities:
-
-- node registry
-- coverage map
-- route selection
-- rebalance directives
-- route-session creation
-- health and telemetry
-- client-visible Generation Telemetry
-- billing/audit records
-
-Must not do:
-
-- serve hot KV during every token
-- become the only place model artifacts can be fetched
-
-### 2. Artifact Plane
-
-Owner: Shard Swarms, local node storage, optional CDN/bootstrap mirrors.
-
-Responsibilities:
-
-- GGUF/safetensors/tokenizer download
-- content-addressed verification
-- local artifact inventory
-- artifact-to-layer mapping
-- cache eviction
-
-Must not do:
-
-- define execution order by file split alone
-- imply that a downloaded file chunk equals a Shard
-
-### 3. Execution Plane
-
-Owner: active Inference Route.
-
-Responsibilities:
-
-- chunked prefill
-- one-step decode
-- hidden-state transfer across activation seams
-- start-layer handling for overlapping shards
-- backpressure
-
-Must not do:
-
-- resend full context activations during decode
-- require cross-node tensor parallel all-reduce for public v1
-
-### 4. Session State Plane
-
-Owner: route nodes for hot KV; cache servers only for snapshots.
-
-Responsibilities:
-
-- per-shard local KV ownership
-- cache allocation and eviction
-- cache ABI compatibility
-- session close/release
-- optional prefix snapshots
-
-Must not do:
-
-- centralize hot KV in a remote service
-- let a replacement node continue from incompatible state
-
-### 5. Economics And Trust Plane
-
-Owner: tracker plus settlement/validation components.
-
-Responsibilities:
-
-- distinguish storage/seeding work from inference work
-- account for prefill and decode separately
-- record route participation
-- sample validation events
-- slash proven fraud
-
-Must not do:
-
-- pay a node for merely holding files as if it generated tokens
-- hide public-swarm privacy limits from clients
-
-## Hard Invariants
-
-These are the framework rules unless we deliberately write a new ADR:
-
-1. Public-network Shards are contiguous layer ranges.
-2. Hot KV State is local to the node serving that Shard in that Route Session.
-3. Artifact distribution and route execution are separate systems.
-4. Decode seam payload must be `O(hidden_size)`.
-5. Prefill may be `O(sequence_length * hidden_size)`, but only in bounded chunks.
-6. The tracker chooses routes; nodes do not negotiate route topology peer-to-peer.
-7. Model/backend-specific cache internals stay behind backend capability reports.
-8. PyTorch remains the correctness/reference backend while llama.cpp/GGUF becomes the performance backend.
-9. Streaming responses are preferred when feasible; Generation Telemetry is always required.
-
-## Resolved Gates
-
-### Gate 1: Public Shard Semantics
-
-Decision: public-network Shards are contiguous transformer layer ranges. Tensor-parallel or ring-style execution is allowed only inside one trusted node, one colocated pod, or a future composite node abstraction.
-
-Rationale:
-
-- Layer ranges match the existing `Shard`, `Coverage Map`, `Inference Route`, billing, and fraud vocabulary.
-- Public volunteer nodes should not require cross-node all-reduce or tight per-layer synchronization in v1.
-- Existing projects such as prima.cpp and Distributed Llama can still inform local-cluster/backend execution without becoming the public routing primitive.
-
-Consequences:
-
-- Artifact Manifests must map files/tensors to semantic layer ranges.
-- Route selection remains ordered layer coverage.
-- Rewards can be attributed to layer-range work.
-- Hot KV State is naturally owned by the node serving that layer range for the Route Session.
-
-### Gate 2: Hot KV Strategy
-
-Decision: v1 rejects centralized hot KV. Hot KV State is local to the node serving the relevant Shard in the active Route Session. Cache servers may store Prefix Snapshots for reuse, retry, or failover, but they are not in the per-token decode path.
-
-Rationale:
-
-- Decode is the tight loop; adding remote cache I/O there makes latency and bandwidth worse at the worst point.
-- Local KV naturally follows layer-range Shard ownership.
-- Centralized hot KV increases privacy exposure and creates consistency problems.
-- Prefix Snapshots preserve the useful part of central storage without making it mandatory for every generated token.
-
-Consequences:
-
-- Route Session must be sticky.
-- Failover is limited in alpha unless a compatible Prefix Snapshot exists.
-- Cache servers are optimization infrastructure, not required runtime infrastructure.
-- Route repair requires compatible model revision, layer range, backend cache ABI, and snapshot position.
-
-### Gate 3: First Runtime Proof
-
-Decision: prove distributed Route Session and Hot KV State semantics in the existing PyTorch route before modifying llama.cpp/GGUF.
-
-Rationale:
-
-- PyTorch exposes model internals and cache objects more directly, so it is the fastest way to validate the distributed protocol.
-- The current distributed PyTorch route already has the right high-level shape but disables cache and recomputes full prompts.
-- Fixing that path gives us a reference implementation for correctness tests, telemetry, session lifecycle, and wire protocol behavior.
-- llama.cpp/GGUF should receive a clear target ABI rather than becoming both the protocol experiment and the performance backend at once.
-
-Consequences:
-
-- Issue 02 precedes issue 05.
-- llama.cpp collaboration has a concrete target ABI.
-- The PyTorch route remains the architecture-coverage/reference backend even after GGUF becomes the preferred performance path.
-- The first success metric is eliminating full-prompt recompute in distributed decode.
-
-### Gate 3A: Client Feedback During Latency
-
-Decision: streaming responses are preferred when feasible, and realtime Generation Telemetry is required regardless of streaming support.
-
-Rationale:
-
-- The product optimizes for access to large capable models, so some latency is acceptable.
-- Users still need confidence that the route is alive and roughly how fast it is generating.
-- Streaming token deltas give the best user experience when the backend exposes them cleanly.
-- Tokens/sec remains useful during prefill, queueing, and any backend that cannot stream token deltas.
-
-Consequences:
-
-- The gateway should stream token deltas through an OpenAI-compatible response when possible.
-- The gateway must expose progress through SSE, WebSocket, or polling.
-- The final answer can be delivered after completion only as a fallback.
-- Telemetry must include route phase, generated token count, and rolling tokens/sec.
-- Non-streaming clients still need realtime telemetry.
-
-### Gate 4: llama.cpp Collaboration Shape
-
-Decision: target upstreamable `libllama`/ggml hooks instead of planning around a permanent fork.
-
-Rationale:
-
-- llama.cpp changes quickly across model support, quantization, kernels, and hardware backends.
-- A permanent fork would become expensive to maintain and would lag upstream improvements.
-- A short-lived prototype branch is acceptable if it proves the API and makes upstream collaboration concrete.
-- Keeping tracker/routing logic outside llama.cpp makes the upstream ask smaller and cleaner.
-
-Consequences:
-
-- Need a minimal reproducible localhost demo before asking upstream to carry the design.
-- Need to separate "what llama.cpp should expose" from "what our tracker does".
-- Desired upstream surface is layer-range execution, hidden-state boundary I/O, partial loading/introspection, and per-session KV ownership.
-- If upstream rejects the shape, we revisit whether to carry a narrow adapter fork or keep GGUF distributed execution as experimental.
-
-### Gate 5: First Model Target
-
-Decision: use a two-tier model target. Use a small, boring, llama.cpp-supported GGUF model for the first protocol smoke test. Use `deepseek-ai/DeepSeek-V4-Flash` as the first serious large-model target. Keep GLM-5.2 and Ornith as later support audits.
-
-Rationale:
-
-- The first protocol proof should isolate route/session/KV bugs from model-architecture bugs.
-- DeepSeek-V4-Flash is a strong first serious target because it is much smaller than 1.6T-class models while still being large enough to validate the product thesis.
-- DeepSeek-V4-Flash still has architecture-specific risks, so it should not be the first smoke test.
-- GLM-5.2 and Ornith remain valuable targets, but they add DSA/MLA/hybrid attention uncertainty.
-
-Consequences:
-
-- 128K cache accounting can be modeled now.
-- The first "real" target-model audit is DeepSeek-V4-Flash support in PyTorch, vLLM/SGLang, and any available GGUF/llama.cpp quantization path.
-- Production support waits for backend capability reports and exact cache ABI support.
-
-### Gate 6: Failure Semantics
-
-Decision: alpha fails Route Sessions on route-node loss instead of attempting automatic route repair.
-
-Rationale:
-
-- Route repair requires compatible Prefix Snapshots, cache ABI checks, replacement-node selection, billing correction, and client stream/error recovery.
-- Local Hot KV State means a replacement node cannot continue unless it has compatible state at the same position.
-- Fail-fast keeps the first implementation correct while the session/KV protocol is still being proven.
-
-Consequences:
-
-- Better observability and explicit errors are required.
-- Snapshotting becomes a later feature, not a blocker for first inference.
-- Generation Telemetry must report the last known phase and failure reason.
-- Client or gateway retry starts a new Route Session from scratch.
-
-### Gate 7: Transport
-
-Decision: keep binary HTTP for v1 activation transfer instead of jumping immediately to QUIC, WebRTC, or a custom transport.
-
-Rationale:
-
-- ADR-0008 already defines binary activation bodies with HTTP headers.
-- HTTP keeps the first implementation debuggable with the existing server stack and tooling.
-- The core risk is route/session/KV correctness, not transport optimization.
-- QUIC/WebRTC can be introduced later behind the same activation protocol once semantics are proven.
-
-Consequences:
-
-- Focus benchmark work on payload shape, chunking, and cache behavior first.
-- QUIC/WebRTC can be introduced as an optimization behind the same activation protocol.
-- v1 implementation can reuse the current HTTP routing, relay, and observability infrastructure.
-- Transport abstraction should be kept narrow enough that HTTP can be replaced later without changing backend cache semantics.
-
-## Grilling Progress
-
-Gates 1, 2, 3, 3A, 4, 5, 6, and 7 are resolved. The remaining work is to convert the resolved framework into implementation-ready issue briefs and prototype milestones.
+# Distributed GGUF Runtime decision framework
+
+> **Specification status:** planning artifacts only. No distributed GGUF runtime is implemented. DGR-017 cleanup is complete; no runtime implementation story has completion credit. `prd.json` is authoritative.
+
+## Decision order
+
+1. DGR-019 locks comparable lanes and thresholds before results.
+2. DGR-020 runs safetensors and whole-model llama.cpp only, then returns `go`, `optimize baseline`, or `stop`.
+3. Dense and V4 work must prove parity, independent per-stage execution, local-state isolation, bounded failure, and measured resources.
+4. DGR-054 returns `alpha`, `optimize measured bottleneck`, or `stop`; MTP is explicitly off.
+5. Post-alpha optimizations must be selected from profiles, not assumptions.
+6. DGR-070 returns `beta`, `targeted optimization`, or `stop/rollback`, and requires MTP and the exact certified hardware/recipe matrix.
+
+## Interpretation rules
+
+- Quant/model-fit gains are separate from runtime/kernel/transport gains.
+- Fixture, real-model, real-hardware, and release evidence are never interchangeable.
+- 2–4 and 10+ stages are certification scenarios only.
+- Existing routing policy is certified, not redesigned.
+- Build success is not hardware certification; dark lanes remain unroutable.
+- Route loss uses cache miss and re-prefill/restart, never WAN cache migration.
+
+## Locked scope
+
+- Existing Meshnet Tracker routing, load balancing, billing, telemetry, relay, and provider semantics are backend-agnostic and are **not redesigned**. GGUF contributes exact compatibility, range/capacity, queue/load, seam-cost, health/reliability, and certification inputs only.
+- The data plane is a standalone project-owned C++ Shard worker with gRPC/Protobuf and a project-owned `ShardEngine` boundary.
+- llama.cpp is fetched at one exact commit into an ignored workspace from an in-repo manifest, then a numbered minimal patch stack is applied. There is no submodule, vendored tree, or permanent-fork dependency.
+- llama.cpp owns DeepSeek V4 graphs, mHC, MoE, attention, hash routing, and kernels. Meshnet adds only range-ownership hooks, typed boundary/local-state adapters, worker integration, and parity/certification.
+- Quantization and placement are dynamic recipe inputs. The 2–4 and 10+ stage layouts are certification scenarios, never product constants.
+- Per-shard Hot KV and V4 CSA/HCA/SWA/indexer/compressor state remain local and keyed by route session/epoch. The WAN seam carries the typed mHC 4×4096 residual boundary, positions, token-ID sideband where required, and schema/cache expectations—not per-layer caches.
+- Route changes use cache miss plus re-prefill/restart. There is no WAN KV or V4 auxiliary-cache migration.
+- CPU/CUDA/ROCm/Vulkan/Metal compile lanes are planned; only exact real-hardware-certified backend/model/recipe lanes may be advertised.
+- Alpha requires correctness and the pre-locked useful-speed gate. MTP is reserved and off for alpha; its ownership contract, implementation, and benchmark are required before beta.
+
+## Target identities
+
+- DeepSeek V4 official target SHA: `60d8d70770c6776ff598c94bb586a859a38244f1`.
+- llama.cpp V4 support lineage began at PR 24162 / merge `8c146a8366304c871efc26057cc90370ccf58dad`; DGR-027 later pins one exact validated current commit.
+- V4 scope: 43 main layers plus MTP; mHC 4×4096 boundary; 256 routed + 1 shared experts with six routed active; token IDs required for the first three hash-routed layers.
+- Exact split-GGUF artifacts are provisioned to mounted-drive storage with a complete hashed manifest and resumable verification; no model artifact may be placed under `/home`.

.scratch/distributed-gguf-runtime/evidence/DGR-001/README.md

@@ -1,127 +0,0 @@
-# DGR-001 — performance contract baseline
-
-## Files changed
-
-- `packages/node/meshnet_node/performance_contract.py`
-- `tests/test_performance_contract.py`
-- `.scratch/distributed-gguf-runtime/issues/01-lock-the-safetensors-versus-gguf-performance-contract.md`
-- `.scratch/distributed-gguf-runtime/evidence/DGR-001/performance-contract.json`
-
-## What this slice does
-
-- Locks the DGR-001 benchmark contract in code.
-- Pins the architecture-aligned baseline to **DeepSeek-V2-Lite-Chat** (`deepseek2`).
-- Uses the same model on both sides of the comparison:
-  - **safetensors:** `deepseek-ai/DeepSeek-V2-Lite-Chat` in **BF16**
-  - **GGUF:** `second-state/DeepSeek-V2-Lite-Chat-GGUF` in **Q2_K**
-- Exposes a machine-readable JSON contract with:
-  - benchmark lanes for `transformers` safetensors and `llama.cpp` GGUF on **CPU** and **GPU**
-  - concurrency levels `1` and `4`
-  - the required metrics list
-  - an explicit stop condition for “no meaningful speed or fit benefit”
-- Adds a deterministic stub benchmark report so the contract now has an executable report shape end to end.
-
-## Recent benchmark runner slice
-
-The runner currently uses a deterministic stub backend to exercise the comparison matrix without downloading a model. It emits:
-
-- `.scratch/distributed-gguf-runtime/evidence/DGR-001/performance-contract.json`
-- `.scratch/distributed-gguf-runtime/evidence/DGR-001/stub-benchmark-report.json`
-
-The report includes per-device comparisons for:
-
-- `transformers-safetensors-cpu` vs `llama-cpp-gguf-cpu`
-- `transformers-safetensors-gpu` vs `llama-cpp-gguf-gpu`
-
-and records the memory metric (`rss_bytes` on CPU, `vram_bytes` on GPU), decode speedup, artifact ratio, and output drift.
-
-## Live endpoint CLI wiring
-
-The contract CLI can now drive the live endpoint runner. Passing one `--live-endpoint LANE_ID=URL` mapping per contract lane (plus `--live-benchmark-out`) invokes `run_real_model_endpoint_benchmark` against already-running OpenAI-compatible servers and writes the report using the same schema as the stub:
-
-```bash
-PYTHONPATH=packages/node python -m meshnet_node.performance_contract \
-  --live-endpoint transformers-safetensors-cpu=http://127.0.0.1:8001 \
-  --live-endpoint llama-cpp-gguf-cpu=http://127.0.0.1:8002 \
-  --live-endpoint transformers-safetensors-gpu=http://127.0.0.1:8003 \
-  --live-endpoint llama-cpp-gguf-gpu=http://127.0.0.1:8004 \
-  --live-benchmark-out .scratch/distributed-gguf-runtime/evidence/DGR-001/live-benchmark-report.json
-```
-
-`--live-model` overrides the model name sent in requests (defaults to the contract's safetensors repo). Without any `--live-endpoint` flags the CLI behaves exactly as before: it writes the contract JSON and, with `--benchmark-out`, the deterministic stub report.
-
-## Exact commands and real results
-
-### Targeted tests
-
-```bash
-PYTHONPATH=packages/node pytest -q tests/test_performance_contract.py tests/test_route_session_benchmark.py
-```
-
-Result: `19 passed in 0.11s`
-
-### Contract artifact generation
-
-```bash
-PYTHONPATH=packages/node python -m meshnet_node.performance_contract --json-out .scratch/distributed-gguf-runtime/evidence/DGR-001/performance-contract.json
-```
-
-Result: wrote `.scratch/distributed-gguf-runtime/evidence/DGR-001/performance-contract.json`
-
-### Python compile check
-
-```bash
-python -m compileall packages/node/meshnet_node/performance_contract.py tests/test_performance_contract.py
-```
-
-Result: passed
-
-## Public relay smoke benchmark (2026-07-15)
-
-A real streamed request was run through the public tracker — **not** by connecting directly to the private node address:
-
-```text
-https://meshnet.2.d-popov.com/v1/chat/completions
-  -> wss://meshnet.2.d-popov.com/ws
-  -> wss://meshnet.2.d-popov.com/rpc/7j77FsPY1evV8tuf-7000
-  -> local CUDA node, Qwen/Qwen2.5-0.5B-Instruct layers 0-23
-```
-
-The local public-tracker node had an expired proof and a wedged HTTP server. A graceful restart refreshed its CUDA capability proof in `336 ms`, restored `admitted`/`routable` status, and reconnected its relay endpoint.
-
-Measured streaming results after recovery:
-
-| metric | result |
-| --- | ---: |
-| warm-up TTFT | 420.80 ms |
-| warm-up elapsed | 610.23 ms |
-| p50 TTFT (3 runs) | 288.26 ms |
-| p50 elapsed (3 runs) | 363.20 ms |
-| tracker-recorded relay throughput | 58.18-65.25 tok/s |
-| HTTP status | 200 for all runs |
-
-The tracker recorded `relay: true` and the local node ID `7j77FsPY-b32476219492` for each completion. Full redacted evidence is in `public-relay-smoke-benchmark.json`.
-
-The other connected node is still alive but **not routable** because its capability proof is stale. It must revalidate before a multi-node shard/relay test can run.
-
-## Limitations
-
-- This slice still uses a deterministic stub backend for the core comparison matrix.
-- It now also includes a live endpoint runner, reachable from the CLI via `--live-endpoint`/`--live-benchmark-out`, that fans out one OpenAI-compatible request per lane when the caller provides endpoints; the CLI does not start those servers.
-- It does **not** download or run a real model from within the repo.
-- Real safetensors vs GGUF execution, TTFT/prefill/decode measurements, RSS/VRAM capture, and output-drift comparison are still to be implemented against the contract.
-
-## Compatibility notes
-
-- The contract stays on the DeepSeek2 family to remain close to the DeepSeek-V4-Flash end goal.
-- A smaller non-DeepSeek model can still be used later for loader-plumbing smoke tests, but it does not replace this baseline.
-- Model artifacts must stay on the mounted drive and not under `/home`.
-
-## Dependent-story handoff
-
-Next implementation work should attach to this contract and add the live benchmark runner that actually compares:
-
-1. current Transformers/safetensors recipe
-2. whole-model llama.cpp GGUF recipe
-
-using the same model architecture/revision and the same prompt/context/concurrency settings.

.scratch/distributed-gguf-runtime/evidence/DGR-001/performance-contract.json

@@ -1,75 +0,0 @@
-{
-  "benchmark_lanes": [
-    {
-      "concurrency_levels": [
-        1,
-        4
-      ],
-      "device": "cpu",
-      "id": "transformers-safetensors-cpu",
-      "recipe": "current safetensors recipe",
-      "runtime": "transformers"
-    },
-    {
-      "concurrency_levels": [
-        1,
-        4
-      ],
-      "device": "cpu",
-      "id": "llama-cpp-gguf-cpu",
-      "recipe": "whole-model GGUF recipe",
-      "runtime": "llama.cpp"
-    },
-    {
-      "concurrency_levels": [
-        1,
-        4
-      ],
-      "device": "gpu",
-      "id": "transformers-safetensors-gpu",
-      "recipe": "current safetensors recipe",
-      "runtime": "transformers"
-    },
-    {
-      "concurrency_levels": [
-        1,
-        4
-      ],
-      "device": "gpu",
-      "id": "llama-cpp-gguf-gpu",
-      "recipe": "whole-model GGUF recipe",
-      "runtime": "llama.cpp"
-    }
-  ],
-  "metrics": [
-    "ttft_ms",
-    "prefill_tok_per_sec",
-    "decode_tok_per_sec",
-    "p50_latency_ms",
-    "p95_latency_ms",
-    "aggregate_throughput_tok_per_sec",
-    "rss_bytes",
-    "vram_bytes",
-    "artifact_bytes",
-    "failure_count",
-    "output_drift"
-  ],
-  "model_target": {
-    "architecture": "deepseek2",
-    "comparison_policy": "same model/revision, closest practical low-footprint precision pair: BF16 safetensors versus Q2_K GGUF",
-    "gguf_quant": "Q2_K",
-    "gguf_repo": "second-state/DeepSeek-V2-Lite-Chat-GGUF",
-    "gguf_size_gb": 6.43,
-    "name": "DeepSeek-V2-Lite-Chat",
-    "rationale": "Smallest DeepSeek-family benchmark anchor that still points toward DeepSeek-V4-Flash; keeps the runtime on the DeepSeek2 path instead of falling back to a tiny but architecture-mismatched smoke model.",
-    "safetensors_precision": "bfloat16",
-    "safetensors_repo": "deepseek-ai/DeepSeek-V2-Lite-Chat"
-  },
-  "notes": [
-    "Real model execution stays opt-in and must keep model artifacts on the mounted drive.",
-    "Use the tiny fallback only for loader plumbing smoke tests; it does not replace the architecture-aligned baseline."
-  ],
-  "schema_version": 1,
-  "stop_condition": "Stop if GGUF does not provide a meaningful speed or fit benefit over the safetensors baseline for the chosen DeepSeek-family model target.",
-  "story_id": "DGR-001"
-}

.scratch/distributed-gguf-runtime/evidence/DGR-001/stub-benchmark-report.json

@@ -1,247 +0,0 @@
-{
-  "comparisons": {
-    "cpu": {
-      "artifact_bytes_ratio": 0.2048,
-      "decode_speedup": 2.3333,
-      "gguf_benefit": true,
-      "gguf_lane": "llama-cpp-gguf-cpu",
-      "memory_bytes_ratio": 0.2152,
-      "memory_metric": "rss_bytes",
-      "output_drift": 0.0,
-      "safetensors_lane": "transformers-safetensors-cpu",
-      "ttft_speedup": 1.8947
-    },
-    "gpu": {
-      "artifact_bytes_ratio": 0.2048,
-      "decode_speedup": 1.5294,
-      "gguf_benefit": true,
-      "gguf_lane": "llama-cpp-gguf-gpu",
-      "memory_bytes_ratio": 0.2273,
-      "memory_metric": "vram_bytes",
-      "output_drift": 0.0,
-      "safetensors_lane": "transformers-safetensors-gpu",
-      "ttft_speedup": 1.6154
-    }
-  },
-  "lanes": [
-    {
-      "concurrency_levels": [
-        1,
-        4
-      ],
-      "device": "cpu",
-      "id": "transformers-safetensors-cpu",
-      "output_tokens": [
-        "mesh",
-        "activation",
-        "seam",
-        "baseline"
-      ],
-      "recipe": "current safetensors recipe",
-      "results": [
-        {
-          "concurrency": 1,
-          "metrics": {
-            "aggregate_throughput_tok_per_sec": 6.0,
-            "artifact_bytes": 33715493273,
-            "decode_tok_per_sec": 6.0,
-            "failure_count": 0,
-            "output_drift": 0.0,
-            "p50_latency_ms": 166.6667,
-            "p95_latency_ms": 208.3334,
-            "prefill_tok_per_sec": 45.0,
-            "rss_bytes": 35433480192,
-            "ttft_ms": 1800.0,
-            "vram_bytes": 0
-          }
-        },
-        {
-          "concurrency": 4,
-          "metrics": {
-            "aggregate_throughput_tok_per_sec": 20.4,
-            "artifact_bytes": 33715493273,
-            "decode_tok_per_sec": 5.1,
-            "failure_count": 0,
-            "output_drift": 0.0,
-            "p50_latency_ms": 196.0784,
-            "p95_latency_ms": 245.098,
-            "prefill_tok_per_sec": 38.25,
-            "rss_bytes": 35433480192,
-            "ttft_ms": 2340.0,
-            "vram_bytes": 0
-          }
-        }
-      ],
-      "runtime": "transformers"
-    },
-    {
-      "concurrency_levels": [
-        1,
-        4
-      ],
-      "device": "cpu",
-      "id": "llama-cpp-gguf-cpu",
-      "output_tokens": [
-        "mesh",
-        "activation",
-        "seam",
-        "baseline"
-      ],
-      "recipe": "whole-model GGUF recipe",
-      "results": [
-        {
-          "concurrency": 1,
-          "metrics": {
-            "aggregate_throughput_tok_per_sec": 14.0,
-            "artifact_bytes": 6904159928,
-            "decode_tok_per_sec": 14.0,
-            "failure_count": 0,
-            "output_drift": 0.0,
-            "p50_latency_ms": 71.4286,
-            "p95_latency_ms": 89.2858,
-            "prefill_tok_per_sec": 90.0,
-            "rss_bytes": 7623566950,
-            "ttft_ms": 950.0,
-            "vram_bytes": 0
-          }
-        },
-        {
-          "concurrency": 4,
-          "metrics": {
-            "aggregate_throughput_tok_per_sec": 47.6,
-            "artifact_bytes": 6904159928,
-            "decode_tok_per_sec": 11.9,
-            "failure_count": 0,
-            "output_drift": 0.0,
-            "p50_latency_ms": 84.0336,
-            "p95_latency_ms": 105.042,
-            "prefill_tok_per_sec": 76.5,
-            "rss_bytes": 7623566950,
-            "ttft_ms": 1235.0,
-            "vram_bytes": 0
-          }
-        }
-      ],
-      "runtime": "llama.cpp"
-    },
-    {
-      "concurrency_levels": [
-        1,
-        4
-      ],
-      "device": "gpu",
-      "id": "transformers-safetensors-gpu",
-      "output_tokens": [
-        "mesh",
-        "activation",
-        "seam",
-        "baseline"
-      ],
-      "recipe": "current safetensors recipe",
-      "results": [
-        {
-          "concurrency": 1,
-          "metrics": {
-            "aggregate_throughput_tok_per_sec": 34.0,
-            "artifact_bytes": 33715493273,
-            "decode_tok_per_sec": 34.0,
-            "failure_count": 0,
-            "output_drift": 0.0,
-            "p50_latency_ms": 29.4118,
-            "p95_latency_ms": 36.7647,
-            "prefill_tok_per_sec": 850.0,
-            "rss_bytes": 4294967296,
-            "ttft_ms": 420.0,
-            "vram_bytes": 35433480192
-          }
-        },
-        {
-          "concurrency": 4,
-          "metrics": {
-            "aggregate_throughput_tok_per_sec": 115.6,
-            "artifact_bytes": 33715493273,
-            "decode_tok_per_sec": 28.9,
-            "failure_count": 0,
-            "output_drift": 0.0,
-            "p50_latency_ms": 34.6021,
-            "p95_latency_ms": 43.2526,
-            "prefill_tok_per_sec": 722.5,
-            "rss_bytes": 4294967296,
-            "ttft_ms": 546.0,
-            "vram_bytes": 35433480192
-          }
-        }
-      ],
-      "runtime": "transformers"
-    },
-    {
-      "concurrency_levels": [
-        1,
-        4
-      ],
-      "device": "gpu",
-      "id": "llama-cpp-gguf-gpu",
-      "output_tokens": [
-        "mesh",
-        "activation",
-        "seam",
-        "baseline"
-      ],
-      "recipe": "whole-model GGUF recipe",
-      "results": [
-        {
-          "concurrency": 1,
-          "metrics": {
-            "aggregate_throughput_tok_per_sec": 52.0,
-            "artifact_bytes": 6904159928,
-            "decode_tok_per_sec": 52.0,
-            "failure_count": 0,
-            "output_drift": 0.0,
-            "p50_latency_ms": 19.2308,
-            "p95_latency_ms": 24.0385,
-            "prefill_tok_per_sec": 640.0,
-            "rss_bytes": 1610612736,
-            "ttft_ms": 260.0,
-            "vram_bytes": 8053063680
-          }
-        },
-        {
-          "concurrency": 4,
-          "metrics": {
-            "aggregate_throughput_tok_per_sec": 176.8,
-            "artifact_bytes": 6904159928,
-            "decode_tok_per_sec": 44.2,
-            "failure_count": 0,
-            "output_drift": 0.0,
-            "p50_latency_ms": 22.6244,
-            "p95_latency_ms": 28.2805,
-            "prefill_tok_per_sec": 544.0,
-            "rss_bytes": 1610612736,
-            "ttft_ms": 338.0,
-            "vram_bytes": 8053063680
-          }
-        }
-      ],
-      "runtime": "llama.cpp"
-    }
-  ],
-  "model_target": {
-    "architecture": "deepseek2",
-    "comparison_policy": "same model/revision, closest practical low-footprint precision pair: BF16 safetensors versus Q2_K GGUF",
-    "gguf_quant": "Q2_K",
-    "gguf_repo": "second-state/DeepSeek-V2-Lite-Chat-GGUF",
-    "gguf_size_gb": 6.43,
-    "name": "DeepSeek-V2-Lite-Chat",
-    "rationale": "Smallest DeepSeek-family benchmark anchor that still points toward DeepSeek-V4-Flash; keeps the runtime on the DeepSeek2 path instead of falling back to a tiny but architecture-mismatched smoke model.",
-    "safetensors_precision": "bfloat16",
-    "safetensors_repo": "deepseek-ai/DeepSeek-V2-Lite-Chat"
-  },
-  "schema_version": 1,
-  "source": "stub-backend",
-  "stop_condition": {
-    "gguf_benefit": true,
-    "text": "Stop if GGUF does not provide a meaningful speed or fit benefit over the safetensors baseline for the chosen DeepSeek-family model target.",
-    "triggered": false
-  },
-  "story_id": "DGR-001"
-}

.scratch/distributed-gguf-runtime/evidence/DGR-002/README.md

@@ -1,176 +0,0 @@
-# DGR-002 — Versioned gRPC Shard protocol: evidence
-
-Status: done
-Date: 2026-07-15
-Evidence kind: **synthetic-unit** (schema round-trip + cross-language protobuf
-compatibility). No model download, no GPU, no network, no API credits.
-
-## Summary
-
-Added the versioned Protocol Buffers schema that is the semantic contract between
-Python and C++ Shards (ADR-0024), plus reproducible Python and C++ code
-generation/build wiring and generated-schema round-trip + compatibility tests in
-**both** languages. The schema defines one long-lived bidirectional gRPC stream
-per Route Session Activation Seam, bounded prefill chunking, a small decode fast
-path, and a versioned named-tensor bundle carrying every required identifier.
-
-No existing runtime code was modified — this story is purely additive (a new
-`.proto`, a `native_protocol` loader package, C++ build wiring, and one new test
-module). Generated stubs are produced on demand into gitignored `build/`
-directories, so nothing generated is committed.
-
-## Files changed (all new)
-
-- `packages/node/native/proto/shard_runtime.proto` — the schema (package
-  `meshnet.shard.v1`, proto3). Service `ShardRuntime` with `GetCapability`,
-  `Health`, `ActivateSession` (bidi stream), `Release`, `Cancel`.
-- `packages/node/meshnet_node/native_protocol/__init__.py` — reproducible
-  on-demand `grpc_tools.protoc` codegen + loader (`load()`, `load_grpc()`) and
-  shared bundle helpers (`compute_checksum`, `verify_checksum`, `fragment_tensor`,
-  `reassemble_tensor`).
-- `packages/node/native/scripts/generate_python.py` — standalone reproducible
-  Python generation (self-contained; does not import `meshnet_node`).
-- `packages/node/native/scripts/generate_cpp.sh` — reproducible C++ generation
-  (message stubs always; gRPC service stubs when `grpc_cpp_plugin` is present).
-- `packages/node/native/CMakeLists.txt` — C++ build wiring; works with both
-  CONFIG-mode (`protobuf::libprotobuf`/`protobuf::protoc`) and CMake's
-  `FindProtobuf` module.
-- `packages/node/native/tests/roundtrip_test.cpp` — C++ round-trip / compat test
-  (`--selftest`, `--read`, `--write`).
-- `tests/test_native_shard_protocol.py` — Python round-trip + compatibility tests
-  and the Python↔C++ cross-language driver.
-
-## Acceptance criteria → evidence
-
-- **Capability/health/session-stream/release/cancellation schema** — the
-  `ShardRuntime` service's five RPCs; `test_capability_and_health_round_trip`,
-  `test_session_stream_carries_open_prefill_decode_release_cancel`.
-- **One long-lived bidi stream per Activation Seam with deadlines, cancellation,
-  flow control, structured errors** — `rpc ActivateSession (stream ...) returns
-  (stream ...)`. Deadlines: gRPC call deadline on direct transport, plus
-  `SessionOpen.deadline_unix_nanos` for relay-carried frames. Cancellation:
-  `Cancel` RPC and in-stream `CancelRequest`/`PHASE_CANCEL`. Flow control:
-  `FlowControl` frames (credits + in-flight byte/message caps). Structured errors:
-  `Status` (canonical code, message, `RetryClass`, details). Verified by
-  `test_session_response_carries_structured_status_and_results`.
-- **Bounded prefill chunking + small decode fast path** — `PrefillChunk`
-  (`chunk_index`/`chunk_count`/`final_chunk`, `SessionOpen.max_prefill_tokens_per_chunk`)
-  and `DecodeStep` (minimal single-bundle path). Bounded fragments via
-  `SessionOpen.max_fragment_bytes` and `fragment_tensor(...)`.
-- **Carries schema version, work ID, Route Session ID, route epoch,
-  artifact/recipe fingerprint, shard range/effective start, phase, position,
-  idempotency step, cache expectation, compression, checksum** — all on
-  `MessageHeader` (+ `ArtifactFingerprint.runtime_recipe_fingerprint`,
-  `ShardRange.effective_start_layer`). Verified field-by-field by
-  `test_message_header_carries_every_required_field`.
-- **Versioned named-tensor bundle (name, shape, dtype, byte order, fragments)** —
-  `TensorBundle`/`NamedTensor`/`TensorFragment`;
-  `test_named_tensor_bundle_describes_shape_dtype_byteorder_and_fragments`,
-  `test_fragment_and_reassemble_round_trip_with_checksums`.
-- **Round-trip + compatibility tests in Python and C++** — Python:
-  `tests/test_native_shard_protocol.py` (11 tests). C++: `roundtrip_test.cpp`
-  built via CMake; cross-language driver `test_cross_language_roundtrip_python_and_cpp`
-  exercises Python→C++ and C++→Python in both directions.
-- **Targeted pytest** — `11 passed, 1 skipped` (default env); `12 passed` with the
-  C++ toolchain on PATH.
-- **compileall packages tests** — exit 0.
-- **git diff --check** — clean.
-- **Deterministic / download-free / credit-free / GPU-free** — all tests are pure
-  protobuf serialization; the C++ path uses only local compilers.
-- **Full deterministic pytest** — `704 passed, 14 skipped, 11 failed`. The 11
-  failures are pre-existing and unrelated (see below).
-
-## Commands and real results
-
-See `commands.txt` for the exact command list. Key results:
-
-- `python packages/node/native/scripts/generate_python.py` →
-  `shard_runtime_pb2.py: ok`, `shard_runtime_pb2_grpc.py: ok`.
-- `pytest tests/test_native_shard_protocol.py -q` → **11 passed, 1 skipped**
-  (skip reason: `C++ toolchain unavailable: cmake not found on PATH`).
-- With `/tmp/pbsrc/install/bin` (protoc 33.1) and `.venv/bin` (cmake) on PATH and
-  `CMAKE_PREFIX_PATH=/tmp/pbsrc/install`:
-  - `generate_cpp.sh` → `shard_runtime.pb.cc`, `shard_runtime.pb.h`
-    (grpc service stubs skipped: `grpc_cpp_plugin` absent).
-  - `cmake -S ... -B ...` + `cmake --build ...` → build OK.
-  - `shard_protocol_roundtrip_test --selftest` → `selftest ok (128 bytes)`, exit 0.
-  - `ctest` → `1/1 Test #1: shard_protocol_roundtrip ... Passed`.
-  - `pytest ...::test_cross_language_roundtrip_python_and_cpp -q` → **1 passed**
-    (Python serializes → C++ parses & verifies → C++ serializes → Python parses
-    & verifies).
-- `compileall -q packages tests` → exit 0.
-- `git diff --check` → clean.
-
-## Pre-existing unrelated failures (full-suite)
-
-`pytest -q` on the full tree reports 11 failures, all in tracker routing /
-dynamic routing / manual route benchmark / toploc calibration — none import the
-Shard protocol. Clean-tree reproduction: with **all DGR-002 files moved aside**
-(`git status` shows only the pre-existing `.ralph-tui/config.toml` deletion),
-re-running exactly these tests gives `11 failed, 3 passed` — identical failures.
-They exist on the `ralph/distributed-gguf-runtime` branch independent of this
-story. The full list is in `results.json.preexisting_unrelated_failures`.
-
-Note: the earlier `progress.md` (RCR-001, on master) recorded a different set of
-6 optional-dependency failures (zstandard, langchain_openai). Those did **not**
-recur here; this environment has those deps. The 11 above are branch-local
-routing/benchmark failures, not environmental.
-
-## Limitations and deferred work
-
-- **C++ toolchain is host-provided, not vendored.** The default test env has no
-  `protoc`/`cmake`/protobuf C++ headers on PATH, so the C++ cross-language test
-  **skips** by default (explicit skip reason). It was executed for this evidence
-  using an ephemeral from-source protobuf 33.1 install at `/tmp/pbsrc/install`
-  plus the `.venv` cmake. DGR-004/DGR-008 should pin the C++ protobuf/gRPC
-  toolchain (upstream commit + reproducible fetch/build) so this test runs in CI
-  without relying on an ad-hoc `/tmp` install.
-- **gRPC C++ service stubs not built here.** `grpc_cpp_plugin` is absent, so
-  `generate_cpp.sh` produced message stubs only. The round-trip test needs only
-  message serialization; the service stubs are DGR-008's concern.
-- **No live gRPC transport yet.** This story delivers the schema + serialization
-  contract and generation/build wiring only. Channel setup, the bidi stream
-  server/client, deadlines/cancellation propagation over a real HTTP/2 channel,
-  and relay framing are DGR-008/DGR-009.
-- **Protobuf runtime version skew.** Python runtime is pip protobuf 7.35.1; the
-  C++ side used protoc 33.1. Protobuf wire format is stable across these, and the
-  cross-language round-trip confirms interop; version pinning is deferred to the
-  toolchain-pinning stories.
-
-## Compatibility / migration notes
-
-- proto3 with a 0-valued `*_UNSPECIFIED` member on every enum and never-reused
-  field numbers. Forward compatibility (unknown-field preservation) is verified
-  behaviourally by `test_unknown_fields_are_preserved_for_forward_compatibility`
-  — note protobuf 7.x's upb backend does not implement the `UnknownFields()`
-  introspection accessor, so the test asserts the observable re-serialization
-  outcome instead. Backward defaults verified by
-  `test_defaults_are_stable_for_backward_compatibility`.
-- Wire schema version is `SchemaVersion.SCHEMA_VERSION_1` (int 1), also exposed as
-  `meshnet_node.native_protocol.SCHEMA_VERSION`.
-
-## Handoff for dependent stories
-
-- **DGR-003 (recipe/fingerprint):** populate `ArtifactFingerprint`
-  (`model_id`, `revision`, `artifact_hash`, `quantization`,
-  `runtime_recipe_fingerprint`). Admission compares these before activation; a
-  mismatch is a fatal `Status` (`RetryClass.RETRY_CLASS_FATAL`).
-- **DGR-004 (llama.cpp pin) / DGR-008 (C++ worker):** pin the C++
-  protobuf + gRPC toolchain and add `grpc_cpp_plugin`; then `generate_cpp.sh`
-  emits service stubs and the CMake target can link gRPC. Implement the
-  `ShardRuntime` servicer; map `(route_session_id, route_epoch)` to an isolated
-  llama sequence. Use `SessionOpen` for stream-scoped bounds and `FlowControl`
-  for backpressure.
-- **DGR-009 (Meshnet integration/relay):** the relay may carry serialized
-  `SessionActivation`/`SessionResponse` frames as opaque binary; use the in-message
-  `deadline_unix_nanos`, `CancelRequest`, and `FlowControl` since gRPC call
-  metadata is lost over relay.
-- **Loader usage:** `from meshnet_node import native_protocol as proto;
-  pb2 = proto.load()`. Stubs regenerate automatically when the `.proto` changes
-  (mtime check). `proto.load_grpc()` returns the service stubs (needs the `grpc`
-  runtime).
-- **Gotcha:** the `.venv` installs the meshnet packages editable via a PEP 660
-  meta-path finder pointing at the **main** checkout. Import the worktree copy by
-  ensuring the worktree `packages/node` is on `sys.path` first (conftest already
-  does this for pytest); standalone tooling must derive paths from `__file__` and
-  not `import meshnet_node` (why `generate_python.py` is self-contained).

.scratch/distributed-gguf-runtime/evidence/DGR-002/commands.txt

@@ -1,40 +0,0 @@
-# DGR-002 reproduction commands (run from repo root, project .venv = Python 3.14).
-
-# 1. Generate Python stubs (reproducible; writes to gitignored build/ dir).
-.venv/bin/python packages/node/native/scripts/generate_python.py
-
-# 2. Python round-trip + compatibility tests (default env; C++ test skips if
-#    cmake/protoc absent).
-.venv/bin/python -m pytest tests/test_native_shard_protocol.py -q
-#   => 11 passed, 1 skipped
-
-# 3. Quality gates.
-.venv/bin/python -m compileall -q packages tests    # exit 0
-git diff --check                                     # clean
-
-# 4. Full deterministic suite (records pre-existing unrelated failures).
-.venv/bin/python -m pytest -q
-#   => 704 passed, 14 skipped, 11 failed (all pre-existing, unrelated; see below)
-
-# 5. Clean-tree reproduction of the 11 pre-existing failures (DGR-002 files moved
-#    aside): same 11 fail => not caused by this story.
-
-# --- C++ / cross-language (requires protoc + protobuf C++ dev + cmake) --------
-# On this host a from-source protobuf 33.1 toolchain lives under /tmp/pbsrc/install
-# and cmake ships in the .venv. To execute the C++ test instead of skipping it:
-export PATH="/tmp/pbsrc/install/bin:$PWD/.venv/bin:$PATH"
-export CMAKE_PREFIX_PATH="/tmp/pbsrc/install:$CMAKE_PREFIX_PATH"
-
-# 6. Generate C++ stubs (message stubs always; gRPC service stubs if
-#    grpc_cpp_plugin present).
-packages/node/native/scripts/generate_cpp.sh
-
-# 7. Standalone C++ build + selftest + ctest.
-cmake -S packages/node/native -B packages/node/native/build/cpp
-cmake --build packages/node/native/build/cpp --target shard_protocol_roundtrip_test
-packages/node/native/build/cpp/shard_protocol_roundtrip_test --selftest   # "selftest ok (128 bytes)"
-(cd packages/node/native/build/cpp && ctest --output-on-failure)          # 1/1 passed
-
-# 8. Cross-language Python<->C++ round-trip via the pytest driver (now runs, not skips).
-.venv/bin/python -m pytest tests/test_native_shard_protocol.py::test_cross_language_roundtrip_python_and_cpp -q
-#   => 1 passed

.scratch/distributed-gguf-runtime/evidence/DGR-002/results.json

@@ -1,63 +0,0 @@
-{
-  "task": "DGR-002",
-  "title": "Adopt the versioned gRPC Shard protocol",
-  "schema": {
-    "proto": "packages/node/native/proto/shard_runtime.proto",
-    "package": "meshnet.shard.v1",
-    "syntax": "proto3",
-    "schema_version": 1,
-    "service": "ShardRuntime",
-    "rpcs": ["GetCapability", "Health", "ActivateSession", "Release", "Cancel"],
-    "streaming_seam": "ActivateSession (bidirectional stream)"
-  },
-  "toolchain": {
-    "python": "3.14.6",
-    "protobuf_runtime_python": "7.35.1",
-    "grpcio": "1.82.1",
-    "grpcio_tools": "1.82.1",
-    "cpp_protoc": "libprotoc 33.1",
-    "cpp_protobuf_toolchain": "/tmp/pbsrc/install (from-source protobuf 33.1, ephemeral host build)",
-    "cmake": "4.4.0 (.venv)",
-    "cxx": "g++ (system)"
-  },
-  "generation": {
-    "python_cmd": "python packages/node/native/scripts/generate_python.py",
-    "python_out": "packages/node/native/build/python/shard_runtime_pb2{,_grpc}.py (gitignored)",
-    "cpp_cmd": "packages/node/native/scripts/generate_cpp.sh",
-    "cpp_out": "packages/node/native/build/cpp-gen/shard_runtime.pb.{h,cc} (gitignored)",
-    "cpp_build": "cmake -S packages/node/native -B <build> && cmake --build <build>"
-  },
-  "tests": {
-    "python_default_env": {"passed": 11, "skipped": 1, "note": "C++ cross-language test skips when cmake/protoc absent"},
-    "python_with_cpp_toolchain": {"passed": 12, "skipped": 0},
-    "cpp_selftest_bytes": 128,
-    "cpp_ctest": "1/1 passed",
-    "cross_language": "Python->C++ and C++->Python round-trip verified in both directions"
-  },
-  "quality_gates": {
-    "targeted_pytest": "11 passed, 1 skipped (default); 12 passed with C++ toolchain",
-    "compileall_packages_tests": "exit 0",
-    "git_diff_check": "clean",
-    "full_pytest": {
-      "passed": 704,
-      "skipped": 14,
-      "failed": 11,
-      "failed_are_preexisting_unrelated": true,
-      "clean_tree_reproduction": "same 11 fail with all DGR-002 files removed (11 failed, 3 passed)"
-    }
-  },
-  "preexisting_unrelated_failures": [
-    "tests/test_dynamic_routing.py::test_admin_can_replace_a_served_model_and_release_it",
-    "tests/test_manual_route_benchmark.py::test_pinned_route_uses_named_node",
-    "tests/test_manual_route_benchmark.py::test_unknown_route_node_is_400",
-    "tests/test_manual_route_benchmark.py::test_invalid_route_shape_is_400",
-    "tests/test_manual_route_benchmark.py::test_clients_without_route_are_unaffected",
-    "tests/test_manual_route_benchmark.py::test_benchmark_records_one_and_two_node_routes",
-    "tests/test_toploc_calibration_dispatch.py::test_calibration_run_dispatches_only_solo_capable_nodes",
-    "tests/test_toploc_calibration_dispatch.py::test_calibration_run_persists_corpus_and_results_endpoint_reports_it",
-    "tests/test_toploc_calibration_dispatch.py::test_calibration_run_node_without_commitment_endpoint_is_skipped_not_failed",
-    "tests/test_tracker_routing.py::test_torch_node_applies_tracker_load_shard_directive",
-    "tests/test_tracker_routing.py::test_shard_heal_cycle_surviving_node_covers_dead_peers_gap"
-  ],
-  "evidence_kind": "synthetic-unit (schema round-trip + cross-language protobuf; no model, no GPU, no network, no API credits)"
-}

.scratch/distributed-gguf-runtime/evidence/DGR-003/README.md

@@ -1,86 +0,0 @@
-# DGR-003 — Exact artifact and runtime-recipe identity: evidence
-
-Status: done
-Date: 2026-07-15
-Evidence kind: **synthetic-unit + repo checks**. No model download, no GPU, no network, no API credits.
-
-## Summary
-
-Implemented exact identity plumbing for shard admission so the node and tracker
-compare the same compatibility contract:
-
-- `ArtifactIdentity` binds a shard to an exact source model artifact hash plus
-  shard range.
-- `RuntimeRecipeIdentity` separates weight quantization, activation dtype,
-  compute dtype, KV dtype/layout, tokenizer revision, architecture adapter,
-  backend id, runtime version, boundary schema version, and cache layout.
-- `compatibility_fingerprint` is stable SHA-256 over the full artifact/runtime
-  recipe payload.
-- Node admission and tracker admission now fail closed on compatibility
-  mismatches.
-- Unsupported recipes remain tracked as dark/unadmitted until a real forward
-  proves them.
-
-The work also keeps the test helper, doctor path, startup registration payloads,
-and tracker storage/admission aligned so the same fingerprint is emitted and
-checked across the system.
-
-## Files changed
-
-- `packages/node/meshnet_node/runtime_recipe.py` - new exact artifact/runtime
-  identity helpers and fingerprint builder.
-- `packages/node/meshnet_node/capability.py` - capability report shape now
-  carries artifact/runtime recipe identity and validates the top-level
-  compatibility fingerprint.
-- `packages/node/meshnet_node/admission.py` - fail-closed admission on
-  compatibility fingerprint mismatch.
-- `packages/node/meshnet_node/doctor.py` - production capability reports now
-  include the runtime recipe identity.
-- `packages/node/meshnet_node/testing.py` - test report builder now mirrors the
-  production fingerprint fields.
-- `packages/node/meshnet_node/startup.py` - registration payload now includes
-  the compatibility fingerprint.
-- `packages/tracker/meshnet_tracker/capability.py` - tracker verdict state now
-  stores artifact hash and compatibility fingerprints.
-- `packages/tracker/meshnet_tracker/server.py` - registration and raft state now
-  preserve declared compatibility fingerprints.
-- `tests/test_node_capability.py` - identity shape and fingerprint regression
-  tests.
-- `tests/test_node_admission.py` - fail-closed admission regression tests.
-- `tests/test_tracker_capability_admission.py` - tracker compatibility mismatch
-  regression tests.
-
-## Commands and real results
-
-- `python -m compileall packages tests` -> exit 0.
-- `pytest -q tests/test_node_capability.py` -> `48 passed in 0.09s`.
-- `pytest -q tests/test_node_admission.py` -> `20 passed in 0.11s`.
-- `pytest -q tests/test_tracker_capability_admission.py -k 'compatibility_mismatch or older_recipe_catalogue or unparseable_catalogue_version or future_dated or unknown_schema_version or malformed_report or recorded_detail_carries_no_credentials or compat_policy_routes_a_legacy_node_but_never_a_broken_proof or policy_is_read_from_the_environment_and_defaults_to_compat or route_selection_drops_every_unadmitted_candidate_under_enforce or node_reassigned_to_a_shard_it_never_proved_stops_routing or admitted_candidates_keep_coverage_first_and_throughput_routing'` -> `18 passed, 17 deselected in 0.11s`.
-- `git diff --check` -> exit 0.
-- `pytest -q` -> not green in this sandbox. Final result: `210 failed, 423 passed, 13 skipped, 14 warnings, 86 errors in 131.34s`.
-
-## Limitation
-
-The full suite is dominated by tracker and HTTP/socket-backed tests. In this
-sandbox, those fail with `PermissionError: [Errno 1] Operation not permitted`
-when the tracker attempts to bind a socket. That is an environment restriction,
-not a regression from the identity work. The pure unit slices above pass.
-
-## Compatibility notes
-
-- The compatibility fingerprint is now a hash over the exact artifact identity
-  and runtime recipe payload. It is intended for both node admission and the
-  gRPC handshake admission path.
-- Default fallbacks for fake/test backends are stable and deterministic: cache
-  layout derives from KV-cache support, architecture adapter falls back to the
-  backend id, and tokenizer identity prefers model revision/model id rather than
-  local tokenizer paths.
-
-## Handoff for dependent stories
-
-- DGR-004 / DGR-008 can reuse `runtime_recipe.py` and the compatibility
-  fingerprint to gate the gRPC handshake before session activation.
-- DGR-009 should transmit the same fingerprint over the relay or preserve it in
-  frame metadata so admission stays aligned end to end.
-- Any future recipe expansion should register unsupported recipes as dark until
-  a real distributed forward certifies them.

.scratch/distributed-gguf-runtime/evidence/DGR-004/README.md

@@ -1,130 +0,0 @@
-# DGR-004 — reproducible pinned llama.cpp patch stack evidence
-
-Status: done
-Date: 2026-07-15
-Evidence kind: **synthetic-build + repo checks**. No model download, no GPU,
-no network fetch during validation, no API credits.
-
-## Summary
-
-Implemented the reproducible source-dependency boundary for llama.cpp and kept
-the fork seam narrow and auditable:
-
-- exact pinned upstream commit and repository metadata
-- numbered patch stack isolated under `packages/node/native/llama/patches/`
-- build script that verifies the pin, applies the patch stack, stages notices,
-  and compiles a standalone worker scaffold without manual source copying
-- upstream file assumptions and fail-closed pin checking
-- license/attribution preservation by staging upstream `LICENSE` and `AUTHORS`
-- clean rebuild smoke test that only uses a fake local checkout and does not
-  download a model
-
-The native smoke path is intentionally minimal in this story. It proves the
-reproducible source dependency and build seam without pulling Meshnet protocol
-code into llama.cpp.
-
-## Files changed
-
-- `packages/node/native/llama/UPSTREAM_COMMIT`
-- `packages/node/native/llama/UPSTREAM_REPOSITORY`
-- `packages/node/native/llama/UPSTREAM_ASSUMPTIONS.md`
-- `packages/node/native/llama/README.md`
-- `packages/node/native/llama/patches/0001-add-meshnet-worker-scaffold.patch`
-- `packages/node/native/llama/templates/meshnet_worker.cpp`
-- `packages/node/native/scripts/build_llama_worker.sh`
-- `tests/test_llama_worker_build.py`
-
-## Exact commands and real results
-
-### Native smoke build against a fake pinned checkout
-
-```bash
-tmpdir=$(mktemp -d)
-mkdir -p "$tmpdir/llama.cpp"
-printf 'MIT\n' > "$tmpdir/llama.cpp/LICENSE"
-printf 'AUTHORS\n' > "$tmpdir/llama.cpp/AUTHORS"
-printf '# placeholder\n' > "$tmpdir/llama.cpp/CMakeLists.txt"
-printf '%s\n' 'b3c9d1b846cc80a6360adb6aeaa4fcd8c4c8dcac' > "$tmpdir/llama.cpp/.meshnet-upstream-commit"
-git init -q "$tmpdir/llama.cpp"
-packages/node/native/scripts/build_llama_worker.sh \
-  --source-dir "$tmpdir/llama.cpp" \
-  --build-dir "$tmpdir/build"
-```
-
-Result:
-
-- `meshnet worker scaffold ok`
-- `upstream commit: b3c9d1b846cc80a6360adb6aeaa4fcd8c4c8dcac`
-- `patchset version: 0001`
-- `build ok: /tmp/.../build/meshnet_worker`
-
-### Targeted pytest
-
-```bash
-python -m pytest -q tests/test_llama_worker_build.py
-```
-
-Result: `1 passed in 0.53s`
-
-### Python compile check
-
-```bash
-python -m compileall -q packages tests
-```
-
-Result: exit 0
-
-### Diff hygiene
-
-```bash
-git diff --check
-```
-
-Result: exit 0
-
-### Full deterministic pytest
-
-```bash
-python -m pytest -q
-```
-
-Result: `424 passed, 13 skipped, 210 failed, 86 errors in 131.04s`
-
-The failures are pre-existing sandbox socket failures in tracker/HTTP-backed
-tests. Representative error:
-
-- `PermissionError: [Errno 1] Operation not permitted` when the tracker tries
-  to bind a socket.
-
-This matches the previously observed environment limitation in the DGR-002 and
-DGR-003 evidence and is unrelated to the llama.cpp pin/build scaffold.
-
-## Limitations
-
-- The sandbox does not provide `cmake`, so the smoke build uses the available
-  direct C++ compiler path (`g++` here) instead of a CMake-generated target.
-- The pinned upstream source was not fetched from GitHub during validation.
-  The script supports fetching the exact commit when network access is
-  available, but the validation run used a fake local checkout to keep the test
-  deterministic and model-free.
-- The patch stack in this story is deliberately narrow and additive. It creates
-  a worker scaffold and build seam, not the final llama.cpp runtime patches.
-
-## Compatibility notes
-
-- The exact upstream pin is `b3c9d1b846cc80a6360adb6aeaa4fcd8c4c8dcac`.
-- The build script fails closed if the checkout pin differs from that commit or
-  if the expected upstream files (`LICENSE`, `AUTHORS`, `CMakeLists.txt`) are
-  missing.
-- The patch stack is isolated from Meshnet networking code and can be applied
-  to a clean pinned checkout before later worker stories extend the scaffold.
-- Upstream attribution notices are preserved in the build output by copying the
-  staged `LICENSE` and `AUTHORS` files into `build/.../upstream-notices/`.
-
-## Dependent-story handoff
-
-- DGR-008 can replace the scaffold source with the real supervised C++ worker
-  while keeping the same pin metadata, patch stack, and build script boundary.
-- DGR-005 and later native stories should keep using the same exact pin so the
-  worker seam remains reproducible while range-loading and session logic are
-  added.

.scratch/distributed-gguf-runtime/evidence/DGR-005/README.md

@@ -1,96 +0,0 @@
-# DGR-005 — dense-Llama range-aware GGUF ownership evidence
-
-Status: done
-Date: 2026-07-15
-Evidence kind: **synthetic-unit + repo checks**. No model download, no GPU, no network, no API credits.
-
-## Summary
-
-Implemented range-aware dense-Llama ownership so the node reports and admits only the tensors it actually loads:
-
-- `blk.N.*` tensors are selected strictly by assigned layer range.
-- Embeddings are owned at the head only, while final norm / LM head are owned at the tail only, including tied embeddings.
-- Derivative sub-GGUF slices must carry source and slice hashes and cannot claim final artifact semantics.
-- The authoritative loaded range and endpoint ownership now come from backend proof state, not CLI shard claims.
-- Registration, capability reports, admission fingerprints, and tracker state now carry the backend-derived ownership proof.
-
-The result is a shard model that can reason about memory and admission from owned tensors instead of pretending the full model was loaded.
-
-## Files changed
-
-- `packages/node/meshnet_node/gguf_ownership.py` - dense-Llama tensor selection and authoritative ownership helpers.
-- `packages/node/meshnet_node/capability.py` - shard reports now carry endpoint ownership and parse it round-trip.
-- `packages/node/meshnet_node/doctor.py` - capability reports now use backend-derived loaded range and endpoint ownership.
-- `packages/node/meshnet_node/testing.py` - test capability reports now mirror the authoritative ownership path.
-- `packages/node/meshnet_node/admission.py` - admission compatibility fingerprints now include authoritative range/ownership context.
-- `packages/node/meshnet_node/model_backend.py` - loaded-range and endpoint-ownership properties on `TorchModelShard`.
-- `packages/node/meshnet_node/startup.py` - registration payloads now use the proof-driven shard range.
-- `packages/tracker/meshnet_tracker/capability.py` - tracker capability state preserves endpoint ownership.
-- `tests/test_gguf_ownership.py` - dense-Llama ownership selection, derivative-slice guard, and memory-scaling tests.
-- `tests/test_node_capability.py` - capability report ownership round-trip tests.
-- `tests/test_node_admission.py` - backend-loaded range beats CLI claim regression tests.
-- `tests/test_tracker_capability_admission.py` - tracker capability proof parsing tests.
-
-## Exact commands and real results
-
-### Targeted pytest slices
-
-```bash
-python -m pytest -q tests/test_gguf_ownership.py tests/test_node_capability.py tests/test_node_admission.py
-```
-
-Result: `73 passed`
-
-```bash
-python -m pytest -q tests/test_tracker_capability_admission.py -k 'test_a_passing_report_that_covers_the_registration_is_admitted or test_a_missing_report_is_absent_not_admitted or test_a_failed_report_is_recorded_as_failed or test_a_report_for_a_different_model_is_a_model_mismatch or test_a_report_for_a_different_shard_is_a_shard_mismatch or test_a_report_for_a_different_recipe_than_the_node_declares_is_a_recipe_mismatch or test_a_report_for_a_different_compatibility_fingerprint_is_a_compatibility_mismatch or test_an_older_recipe_catalogue_is_incompatible or test_an_unparseable_catalogue_version_is_incompatible or test_a_stale_report_is_not_admitted or test_a_future_dated_report_is_not_admitted or test_a_report_from_an_unknown_schema_version_is_invalid or test_a_malformed_report_is_invalid_and_never_admitted or test_recorded_detail_carries_no_credentials_from_node_diagnostics or test_compat_policy_routes_a_legacy_node_but_never_a_broken_proof or test_the_policy_is_read_from_the_environment_and_defaults_to_compat'
-```
-
-Result: `22 passed, 13 deselected`
-
-### Python compile check
-
-```bash
-python -m compileall -q packages tests
-```
-
-Result: exit 0
-
-### Diff hygiene
-
-```bash
-git diff --check
-```
-
-Result: exit 0
-
-### Full deterministic pytest
-
-```bash
-python -m pytest -q
-```
-
-Result: `211 failed, 428 passed, 13 skipped, 14 warnings, 86 errors in 135.03s`
-
-The failing set is not caused by this story. The dominant environment issues were:
-
-- tracker and HTTP/socket-backed tests fail with `PermissionError: [Errno 1] Operation not permitted` when the tracker tries to bind sockets in this sandbox
-- native protocol tests fail early with a protobuf runtime/gencode mismatch: generated code expects protobuf 7.35.0 while the installed runtime is 6.33.6
-
-## Limitations
-
-- This evidence is intentionally deterministic and model-free.
-- The memory-scaling check is synthetic: it validates that owned tensor bytes scale with selected tensors, not a live GGUF download.
-- Native C++ code was not changed by this story, so the pinned llama.cpp build validation remains covered by DGR-004 rather than repeated here.
-
-## Compatibility notes
-
-- Dense-Llama ownership is range-first: the shard interior is `blk.N.*`, and endpoint tensors are only attributed to the head or tail owner as appropriate.
-- Derivative GGUF slices are explicitly not final artifacts; they must preserve source and slice hashes if used as a temporary compatibility bridge.
-- The model proof path is authoritative for reported range and endpoint ownership, so operator CLI claims no longer control what the node advertises.
-- Admission and tracker state now consume the same proof-derived ownership shape, keeping capability reports aligned end to end.
-
-## Handoff for dependent stories
-
-- DGR-006 can reuse `gguf_ownership.py` and the new capability fields to wire the shard protocol to proof-derived ownership without re-deriving tensor names.
-- DGR-008 and later routing work should continue to treat endpoint ownership as metadata and `blk.N.*` ownership as the core range contract.
-- If a future temporary slice path is needed, it should keep source/slice hashes visible and avoid claiming final-artifact semantics until a real proof exists.

.scratch/distributed-gguf-runtime/evidence/DGR-006/README.md

@@ -1,203 +0,0 @@
-# DGR-006 — Architecture-defined boundary input/output: evidence
-
-Status: done
-Date: 2026-07-15
-Evidence kind: **synthetic-unit** (pure-numpy dense-Llama reference + boundary
-contract). No model download, no GPU, no torch, no network, no API credit.
-
-## Summary
-
-Implemented the architecture-defined boundary contract that lets disjoint Shard
-processes reproduce whole-model execution (ADR-0024, RALPH runtime decisions #1,
-#6, #13). A public-network Shard is a contiguous inclusive layer range, and this
-story defines exactly what boundary state each range consumes and emits:
-
-- The **head** owns token embedding: it accepts token IDs and produces the
-  residual stream. It refuses an upstream boundary bundle.
-- **Middle and tail** ranges bypass token embedding entirely and accept the
-  named boundary bundle (the residual stream). They refuse token IDs.
-- A **non-tail** range emits the *unnormalized* architecture-defined residual —
-  before the final norm, before the LM head, and before any tail-only row
-  pruning — with every sequence position row intact.
-- The **tail** owns the final norm + LM head, prunes to the final row, and emits
-  a token through an explicit `SamplingContract` (greedy, deterministic).
-- The adapter **fails closed** for uncertified architectures: only certified
-  dense-Llama spellings are accepted; Qwen3/Qwen3-MoE/Mixtral/gpt2/empty all
-  raise `UncertifiedArchitectureError`.
-
-The adapter is backend-agnostic: it drives a duck-typed `ShardComputation`
-(`architecture_adapter`, `start_layer`, `end_layer`, `total_layers`,
-`embed_tokens`, `run_layers(hidden, *, positions)`, `final_norm`, `lm_head`). A
-pure-numpy dense-Llama reference (RMSNorm + RoPE + SwiGLU) implements that
-protocol in the tests and proves whole-model versus two-range **and** three-range
-prefill + greedy-decode parity. torch/transformers are not installed in the
-default `.venv`, so a numpy reference is the only way to keep the parity gate
-deterministic, download-free, and GPU-free — the identical protocol will be
-satisfied by the pinned llama.cpp worker (DGR-008) and the PyTorch backend.
-
-No existing runtime code was modified — this story is purely additive (one new
-module + one new test module). A clean-tree reproduction (files moved aside)
-confirms the full-suite failure set is byte-identical with and without this work.
-
-## Files changed (all new)
-
-- `packages/node/meshnet_node/boundary_adapter.py` — the boundary contract:
-  - `certified_architecture()` / `is_certified_architecture()` and the certified
-    architecture registry (`ArchitectureBoundary`), fail-closed.
-  - `ShardRole` + `role_for_range()` (head/middle/tail/full).
-  - `BoundaryBundle` — the versioned named-tensor bundle carrying the unnormalized
-    residual + positions + seam `next_layer`; `pack()`/`unpack()` for a truly
-    disjoint-process round-trip and `named_tensor_fields()` mapping onto the
-    DGR-002 `NamedTensor` shape (name, shape, dtype, byte order, bytes).
-  - `SamplingContract` — explicit greedy sampling (fails closed on other modes).
-  - `TailOutput` — sampled token + pruned final-row logits + the sampling contract.
-  - `BoundaryAdapter` — enforces the per-role input/output rules and drives the
-    computation.
-- `tests/test_boundary_adapter.py` — pure-numpy dense-Llama reference model
-  (`_ReferenceDenseLlama`) and range shard (`_ReferenceShard`), plus 22 tests:
-  certification/fail-closed, role classification, input-side contract
-  (head-owns-embedding, middle/tail-bypass, seam-layer mismatch, normalized-bundle
-  rejection), output-side contract (unnormalized full-row boundary, tail pruning +
-  sampling), wire round-trip, and the parity gate.
-
-## Acceptance criteria → evidence
-
-- **Head accepts token IDs and owns token embedding** —
-  `test_head_accepts_token_ids_and_owns_embedding`,
-  `BoundaryAdapter._ingest_tokens` (head requires token IDs, refuses a bundle).
-- **Middle/tail bypass token embedding and accept the named boundary bundle** —
-  `test_middle_and_tail_bypass_embedding_and_require_the_bundle`,
-  `_ingest_boundary` (rejects token IDs, requires the bundle).
-- **Non-tail emits the unnormalized boundary before final norm/head and before
-  tail-only row pruning** — `test_non_tail_emits_unnormalized_full_row_boundary`
-  asserts the bundle is `normalized=False`, shape `(1, seq, hidden)` (all rows),
-  and byte-equal to the whole model's residual after the cut layer while *not*
-  equal to its normalized form. `_emit_boundary`.
-- **Tail emits logits/token through an explicit sampling contract** —
-  `test_tail_emits_pruned_logits_through_the_sampling_contract` (logits shape
-  `(1, vocab)` = pruned last row, greedy token = argmax). `_emit_tail`,
-  `SamplingContract`.
-- **Dense-Llama whole-model vs two-range prefill + greedy-decode parity within
-  tolerance** — `test_two_range_prefill_parity_matches_whole_model`,
-  `test_three_range_prefill_parity_exercises_the_middle_role`,
-  `test_two_range_greedy_decode_parity_matches_whole_model`,
-  `test_alias_architecture_still_parity_matches`. Documented tolerance:
-  next-token logits `np.allclose(..., atol=1e-6)` and **identical** greedy token
-  sequences. (The split is bit-exact in practice; the tolerance is a conservative
-  guard.)
-- **Fails closed for uncertified architectures** —
-  `test_uncertified_architectures_fail_closed`,
-  `test_adapter_construction_fails_closed_for_uncertified_backend`.
-- **Targeted pytest** — `22 passed`.
-- **compileall packages tests** — exit 0.
-- **git diff --check** — clean.
-- **Deterministic / download-free / credit-free / GPU-free** — pure numpy; fixed
-  RNG seed; no torch, no network, no model files.
-- **Full deterministic pytest** — `20 failed, 715 passed, 13 skipped, 12 errors`.
-  All 20 failures + 12 errors are pre-existing and unrelated (see below).
-- **Native C++ / CTest / llama.cpp patch stack** — **not touched by this story.**
-  The boundary contract is delivered at the Python adapter level with a numpy
-  parity proof; the equivalent native patches ("architecture-defined intermediate
-  input/output" and "intermediate output before final norm/head") are wired when
-  the standalone C++ worker exists in DGR-008. No native code, CMake, or llama.cpp
-  patch was modified, so those gates are N/A here (same as DGR-005).
-
-## Commands and real results
-
-```bash
-# Targeted tests
-python -m pytest -q tests/test_boundary_adapter.py
-# -> 22 passed in 0.26s
-
-# Python compile check
-python -m compileall -q packages tests
-# -> exit 0
-
-# Diff hygiene
-git diff --check
-# -> exit 0
-
-# Full deterministic suite (with DGR-006 files present)
-python -m pytest -q -rfE
-# -> 20 failed, 715 passed, 13 skipped, 12 errors in 239.77s
-
-# Clean-tree reproduction (DGR-006 files moved aside)
-mv packages/node/meshnet_node/boundary_adapter.py /tmp/ && mv tests/test_boundary_adapter.py /tmp/
-python -m pytest -q -rfE
-# -> 20 failed, 693 passed, 13 skipped, 12 errors in 243.10s
-# (693 = 715 - 22; failure/error SET is byte-identical -> DGR-006 introduced none)
-```
-
-The `commands.txt` and `results.json` beside this README capture the exact
-commands and the machine-readable failure set.
-
-## Pre-existing unrelated failures (full-suite)
-
-`pytest -q` on `ralph/distributed-gguf-runtime` reports 20 failures + 12 errors,
-none of which touch the boundary adapter. Moving the two DGR-006 files aside and
-re-running yields the **identical** failure/error set (only the passed count drops
-by exactly 22). Categories:
-
-- **12 errors — `tests/test_native_shard_protocol.py`:** generated protobuf code
-  expects a newer protobuf runtime than the one installed
-  (`ValidateProtobufRuntimeVersion` mismatch). Pre-existing; documented in the
-  DGR-002 / DGR-005 evidence.
-- **20 failures** across `test_activation_compression.py`,
-  `test_dynamic_routing.py`, `test_gossip_and_relay.py`,
-  `test_manual_route_benchmark.py`, `test_node_doctor.py`,
-  `test_openai_gateway.py` (`langchain` optional dep),
-  `test_toploc_calibration_dispatch.py`, `test_tracker_capability_admission.py`,
-  `test_tracker_control_plane.py`, `test_tracker_routing.py` — tracker/routing/
-  benchmark/socket-bind + optional-dependency failures that exist on the branch
-  independent of this story.
-
-## Limitations and deferred work
-
-- **Numpy reference, not real weights.** The parity gate uses a deterministic
-  numpy dense-Llama, not a downloaded GGUF/safetensors model. Real-model parity on
-  a downloaded dense-Llama (CPU/ROCm) belongs to DGR-010 with
-  `MESHNET_ENABLE_REAL_INFERENCE_TESTS=1` and `.venv-rocm`.
-- **Stateless decode for parity.** Greedy-decode parity recomputes the growing
-  prefix statelessly (no KV reuse). Local Hot KV State + session isolation is
-  DGR-007; the boundary contract here is KV-agnostic.
-- **Native patch wiring deferred.** The C++/llama.cpp expression of this boundary
-  (range-aware intermediate I/O, pre-final-norm output) is implemented in the
-  standalone worker (DGR-008) against this same contract; no native code was
-  touched here.
-- **Greedy-only sampling certified.** `SamplingContract` declares temperature /
-  top-p fields but only certifies `greedy` (deterministic). Stochastic sampling is
-  out of scope for the deterministic parity gate.
-
-## Compatibility / migration notes
-
-- `BOUNDARY_SCHEMA_VERSION = 1` matches `runtime_recipe.RuntimeRecipeIdentity`'s
-  `boundary_schema_version`. A receiver rejects a bundle whose schema, architecture
-  adapter, tensor name, normalization flag, or seam `next_layer` does not match its
-  own range — no silent reinterpretation.
-- `BoundaryBundle.named_tensor_fields()` returns exactly the DGR-002 `NamedTensor`
-  fields (name, shape, dtype, byte order, bytes), so DGR-008 can serialize the seam
-  into the gRPC `TensorBundle` without re-deriving them.
-- Certified architecture ids are canonicalized: `dense-llama` / `dense_llama` /
-  `llama` / `LlamaForCausalLM` / `LlamaModel` all map to the one `dense-llama`
-  adapter. Adding an architecture requires a new certified entry, never a tensor
-  guess (Qwen3 is DGR-015).
-
-## Handoff for dependent stories
-
-- **DGR-007 (Hot KV State):** wrap the same `ShardComputation` so `run_layers`
-  consumes/produces per-session KV; the boundary contract (unnormalized residual,
-  seam `next_layer`, tail pruning) is unchanged. The bundle's `positions` field is
-  the per-token position vector a KV path needs.
-- **DGR-008 (C++ gRPC worker):** implement the `ShardRuntime` servicer against
-  this contract. Map `BoundaryBundle.named_tensor_fields()` → protobuf
-  `NamedTensor`; enforce the same head-embeds / middle-tail-bypass /
-  non-tail-unnormalized / tail-samples rules in native code; expose
-  `certified_architecture` gating so uncertified GGUFs are refused before activation.
-- **DGR-009 (Meshnet integration):** carry `BoundaryBundle.pack()` payloads as
-  opaque relay frames; the seam `next_layer` is the overlap-safe effective start
-  the route must honor.
-- **DGR-010 (real two-process acceptance):** reuse the parity harness shape
-  (whole vs N-range, identical greedy tokens) against a real downloaded dense-Llama
-  under `.venv-rocm`.
-- **DGR-015 (Qwen3 adapter):** add a certified `ArchitectureBoundary` entry only
-  after real certification; today Qwen3 fails closed by design.

.scratch/distributed-gguf-runtime/evidence/DGR-006/commands.txt

@@ -1,26 +0,0 @@
-# DGR-006 exact commands (run from repo worktree root)
-
-# Targeted boundary-adapter tests
-python -m pytest -q tests/test_boundary_adapter.py
-# -> 22 passed in 0.26s
-
-# Python compile check for changed Python
-python -m compileall -q packages tests
-# -> exit 0
-
-# Diff hygiene
-git diff --check
-# -> exit 0
-
-# Full deterministic suite with DGR-006 files present
-python -m pytest -q -rfE
-# -> 20 failed, 715 passed, 13 skipped, 12 errors in 239.77s
-
-# Clean-tree reproduction: move the two new DGR-006 files aside, re-run
-mv packages/node/meshnet_node/boundary_adapter.py /tmp/dgr006_boundary_adapter.py
-mv tests/test_boundary_adapter.py /tmp/dgr006_test_boundary_adapter.py
-python -m pytest -q -rfE
-# -> 20 failed, 693 passed, 13 skipped, 12 errors in 243.10s
-# (693 = 715 - 22; failure/error set byte-identical to the with-files run)
-mv /tmp/dgr006_boundary_adapter.py packages/node/meshnet_node/boundary_adapter.py
-mv /tmp/dgr006_test_boundary_adapter.py tests/test_boundary_adapter.py

.scratch/distributed-gguf-runtime/evidence/DGR-006/results.json

@@ -1,161 +0,0 @@
-{
-  "story": "DGR-006",
-  "date": "2026-07-15",
-  "evidence_kind": "synthetic-unit (pure-numpy dense-Llama parity + boundary contract)",
-  "targeted_tests": {
-    "file": "tests/test_boundary_adapter.py",
-    "result": "22 passed"
-  },
-  "compileall": "exit 0",
-  "git_diff_check": "clean",
-  "parity_tolerance": {
-    "logits_atol": 1e-06,
-    "greedy_tokens": "identical"
-  },
-  "full_suite_with_files": {
-    "failed": 20,
-    "passed": 715,
-    "skipped": 13,
-    "errors": 12,
-    "seconds": 239.77
-  },
-  "full_suite_clean_tree": {
-    "failed": 20,
-    "passed": 693,
-    "skipped": 13,
-    "errors": 12,
-    "seconds": 243.1,
-    "note": "693 = 715 - 22 DGR-006 tests; failure/error set identical"
-  },
-  "failure_set_identical_with_and_without_dgr006": true,
-  "preexisting_unrelated_failures": [
-    {
-      "kind": "ERROR",
-      "nodeid": "tests/test_native_shard_protocol.py::test_capability_and_health_round_trip"
-    },
-    {
-      "kind": "ERROR",
-      "nodeid": "tests/test_native_shard_protocol.py::test_checksum_algorithms_verify"
-    },
-    {
-      "kind": "ERROR",
-      "nodeid": "tests/test_native_shard_protocol.py::test_cross_language_roundtrip_python_and_cpp"
-    },
-    {
-      "kind": "ERROR",
-      "nodeid": "tests/test_native_shard_protocol.py::test_defaults_are_stable_for_backward_compatibility"
-    },
-    {
-      "kind": "ERROR",
-      "nodeid": "tests/test_native_shard_protocol.py::test_fragment_and_reassemble_round_trip_with_checksums"
-    },
-    {
-      "kind": "ERROR",
-      "nodeid": "tests/test_native_shard_protocol.py::test_message_header_carries_every_required_field"
-    },
-    {
-      "kind": "ERROR",
-      "nodeid": "tests/test_native_shard_protocol.py::test_named_tensor_bundle_describes_shape_dtype_byteorder_and_fragments"
-    },
-    {
-      "kind": "ERROR",
-      "nodeid": "tests/test_native_shard_protocol.py::test_reassemble_detects_fragment_corruption"
-    },
-    {
-      "kind": "ERROR",
-      "nodeid": "tests/test_native_shard_protocol.py::test_service_descriptor_exposes_all_operations"
-    },
-    {
-      "kind": "ERROR",
-      "nodeid": "tests/test_native_shard_protocol.py::test_session_response_carries_structured_status_and_results"
-    },
-    {
-      "kind": "ERROR",
-      "nodeid": "tests/test_native_shard_protocol.py::test_session_stream_carries_open_prefill_decode_release_cancel"
-    },
-    {
-      "kind": "ERROR",
-      "nodeid": "tests/test_native_shard_protocol.py::test_unknown_fields_are_preserved_for_forward_compatibility"
-    },
-    {
-      "kind": "FAILED",
-      "nodeid": "tests/test_activation_compression.py::test_compressible_body_uses_zstd_when_it_clears_savings_policy"
-    },
-    {
-      "kind": "FAILED",
-      "nodeid": "tests/test_activation_compression.py::test_incompressible_body_stays_raw_after_measured_trial"
-    },
-    {
-      "kind": "FAILED",
-      "nodeid": "tests/test_activation_compression.py::test_malformed_zstd_and_legacy_raw_bodies_are_handled_explicitly"
-    },
-    {
-      "kind": "FAILED",
-      "nodeid": "tests/test_activation_compression.py::test_threshold_requires_both_byte_and_ratio_savings"
-    },
-    {
-      "kind": "FAILED",
-      "nodeid": "tests/test_dynamic_routing.py::test_admin_can_replace_a_served_model_and_release_it"
-    },
-    {
-      "kind": "FAILED",
-      "nodeid": "tests/test_gossip_and_relay.py::test_activation_compression_round_trips_and_skips_small_bodies"
-    },
-    {
-      "kind": "FAILED",
-      "nodeid": "tests/test_manual_route_benchmark.py::test_benchmark_records_one_and_two_node_routes"
-    },
-    {
-      "kind": "FAILED",
-      "nodeid": "tests/test_manual_route_benchmark.py::test_clients_without_route_are_unaffected"
-    },
-    {
-      "kind": "FAILED",
-      "nodeid": "tests/test_manual_route_benchmark.py::test_invalid_route_shape_is_400"
-    },
-    {
-      "kind": "FAILED",
-      "nodeid": "tests/test_manual_route_benchmark.py::test_pinned_route_uses_named_node"
-    },
-    {
-      "kind": "FAILED",
-      "nodeid": "tests/test_manual_route_benchmark.py::test_unknown_route_node_is_400"
-    },
-    {
-      "kind": "FAILED",
-      "nodeid": "tests/test_node_doctor.py::test_cli_doctor_flags_select_what_is_validated"
-    },
-    {
-      "kind": "FAILED",
-      "nodeid": "tests/test_openai_gateway.py::test_langchain_chat_openai"
-    },
-    {
-      "kind": "FAILED",
-      "nodeid": "tests/test_toploc_calibration_dispatch.py::test_calibration_run_dispatches_only_solo_capable_nodes"
-    },
-    {
-      "kind": "FAILED",
-      "nodeid": "tests/test_toploc_calibration_dispatch.py::test_calibration_run_node_without_commitment_endpoint_is_skipped_not_failed"
-    },
-    {
-      "kind": "FAILED",
-      "nodeid": "tests/test_toploc_calibration_dispatch.py::test_calibration_run_persists_corpus_and_results_endpoint_reports_it"
-    },
-    {
-      "kind": "FAILED",
-      "nodeid": "tests/test_tracker_capability_admission.py::test_an_enforcing_tracker_never_routes_a_node_whose_proof_does_not_cover_it[invalid]"
-    },
-    {
-      "kind": "FAILED",
-      "nodeid": "tests/test_tracker_control_plane.py::test_tracker_startup_does_not_import_or_load_model_backends"
-    },
-    {
-      "kind": "FAILED",
-      "nodeid": "tests/test_tracker_routing.py::test_shard_heal_cycle_surviving_node_covers_dead_peers_gap"
-    },
-    {
-      "kind": "FAILED",
-      "nodeid": "tests/test_tracker_routing.py::test_torch_node_applies_tracker_load_shard_directive"
-    }
-  ]
-}

.scratch/distributed-gguf-runtime/evidence/DGR-007/README.md

@@ -1,229 +0,0 @@
-# DGR-007 — Isolated concurrent local Hot KV State: evidence
-
-Status: done
-Date: 2026-07-15
-Evidence kind: **synthetic-unit** (pure-numpy KV-cached dense-Llama reference +
-session/KV manager). No model download, no GPU, no torch, no network, no API
-credit.
-
-## Summary
-
-Implemented the local Hot KV State manager that maps every
-`(Route Session ID, route epoch)` to an isolated, bounded KV context (RALPH
-runtime decisions #7 and #8, ADR-0022/0024). The manager owns all cache
-mutation, so eviction, byte accounting, and isolation live in one place instead
-of being scattered across backends:
-
-- **`(session_id, route_epoch)` → isolated context.** Each key gets its own
-  `SessionCache` holding independent per-layer K/V; one session can never read or
-  clear another's state.
-- **KV allocated only for owned layers.** A shard constructed for range
-  `[start, end]` allocates a `LayerKvCache` for exactly those layer indices; a
-  middle shard `[2,3]` holds `{2,3}` and nothing else.
-- **Full lifecycle:** prefill append, decode append, truncate (rollback),
-  release, TTL eviction, LRU eviction (by session cap and by byte budget), and an
-  **explicit** `CacheMiss` (unknown-session / evicted-ttl / evicted-lru /
-  released / superseded-epoch / seq-len-mismatch) so the head degrades to a
-  from-token-zero re-prefill instead of corrupting output (decision #14).
-- **Fails closed on identity.** Stale route epochs raise `StaleRouteEpochError`; a
-  request carrying an incompatible KV recipe raises `IncompatibleCacheRecipeError`
-  (fingerprint mismatch of architecture / kv dtype / head geometry / owned range);
-  a recipe for an uncertified architecture fails closed at construction (reusing
-  the DGR-006 certified-architecture gate).
-- **KV-aware boundary driver.** `KvBoundaryAdapter` wraps the DGR-006
-  `ShardComputation` (plus `run_layers_cached`) so a shard runs cached
-  prefill/decode through the manager while honouring the architecture-defined
-  boundary contract (head embeds tokens, middle/tail bypass embedding and consume
-  the unnormalized residual bundle, non-tail emits the unnormalized residual, tail
-  normalizes + heads + prunes + samples). The computation returns the new
-  position-encoded K/V; the manager commits it under the budget.
-
-A pure-numpy **KV-cached** dense-Llama reference (RMSNorm + RoPE + SwiGLU with an
-absolute-position causal mask over cached keys) proves that cached prefill/decode
-reproduces the stateless whole-model greedy tokens bit-for-bit, single-range and
-across a head/tail seam. torch/transformers are not installed in the default
-`.venv`, so a numpy reference is the only way to keep the parity + isolation gate
-deterministic, download-free, and GPU-free — the identical manager contract will
-be satisfied by the pinned llama.cpp worker (DGR-008), where the KV context maps
-onto a llama sequence.
-
-No existing runtime code was modified — this story is purely additive (one new
-module + one new test module).
-
-## Files changed (all new)
-
-- `packages/node/meshnet_node/hot_kv_state.py` — the KV/session manager:
-  - `KvCacheRecipe` — KV layout identity (certified architecture, kv dtype, head
-    geometry, owned range) with `fingerprint()` / `is_compatible()` /
-    `bytes_per_token()`; fails closed on uncertified architectures.
-  - `LayerKvCache` — per-owned-layer `(seq, n_kv_heads, head_dim)` K/V with
-    `append` / `truncate` / `nbytes`.
-  - `SessionCache` — the isolated per-`(session, epoch)` context over owned layers.
-  - `CacheMiss` / `CacheMissReason` — the explicit, serializable miss response.
-  - `HotKvStateManager` — `open` / `append` / `truncate` / `release` / `resolve` /
-    `get`, LRU+TTL+byte-budget eviction, stale-epoch + incompatible-recipe
-    rejection, epoch supersession, thread-safe (RLock), injectable clock.
-  - `KvBoundaryAdapter` + `kv_recipe_for()` — KV-aware boundary driver.
-- `tests/test_hot_kv_state.py` — pure-numpy KV-cached dense-Llama reference and 22
-  tests (see below).
-
-## Acceptance criteria → evidence
-
-- **Map `(Route Session ID, route epoch)` to an isolated context** —
-  `test_prefill_then_decode_append_grows_owned_layers`,
-  `test_four_interleaved_sessions_have_no_kv_cross_talk`,
-  `HotKvStateManager.open` keys sessions on `(session_id, route_epoch)`.
-- **Allocate KV only for owned layers** —
-  `test_manager_allocates_kv_only_for_owned_layers` (middle `[2,3]` → `{2,3}`),
-  `test_multi_range_cached_decode_parity_across_a_seam` (head owns `(0,1,2)`, tail
-  owns `(3,4,5)`), `test_recipe_bytes_per_token_scales_with_owned_layers`.
-- **Prefill append / decode append / truncate / release / TTL-LRU eviction /
-  explicit cache-miss** — `test_prefill_then_decode_append_grows_owned_layers`,
-  `test_truncate_rolls_back_all_owned_layers`,
-  `test_release_one_session_leaves_others_intact_and_returns_memory`,
-  `test_ttl_eviction_yields_an_explicit_cache_miss`,
-  `test_lru_eviction_by_session_cap_reports_a_miss`,
-  `test_budget_eviction_keeps_total_within_budget`,
-  `test_unknown_session_is_an_explicit_cache_miss`,
-  `test_seq_len_mismatch_is_an_explicit_cache_miss`.
-- **Reject stale epochs and incompatible cache recipes** —
-  `test_stale_route_epoch_is_rejected`,
-  `test_new_route_epoch_supersedes_and_frees_old_epoch`,
-  `test_incompatible_cache_recipe_is_rejected`,
-  `test_uncertified_architecture_recipe_fails_closed`.
-- **≥ four concurrent sessions complete without token or KV cross-talk** —
-  `test_four_interleaved_sessions_have_no_kv_cross_talk` (four interleaved
-  round-robin sessions, four *distinct* references, each matches its own),
-  `test_four_sessions_on_real_threads_stay_isolated` (four OS threads).
-- **Cancellation/release leaves others intact and memory returns to budget** —
-  `test_release_one_session_leaves_others_intact_and_returns_memory` (released
-  session → `CacheMiss(RELEASED)`, `total_bytes` drops, survivors keep matching
-  their references), `test_single_session_exceeding_budget_raises`.
-- **Cached vs stateless correctness core** —
-  `test_cached_full_shard_decode_matches_stateless_whole_model`,
-  `test_cached_prefill_next_token_matches_whole_model_logits`,
-  `test_multi_range_cached_decode_parity_across_a_seam`. Documented tolerance:
-  **identical** greedy token ids (bit-exact in practice; cached incremental
-  attention equals stateless full-sequence recompute per query row).
-- **Targeted pytest** — `22 passed`.
-- **compileall packages tests** — exit 0.
-- **git diff --check** — clean.
-- **Deterministic / download-free / credit-free / GPU-free** — pure numpy; fixed
-  RNG seed; injectable clock (no wall-clock in tests); no torch, no network, no
-  model files.
-- **Full deterministic pytest** — `13 failed, 755 passed, 14 skipped in 254.50s`.
-  All 13 failures are pre-existing and unrelated; the clean-tree reproduction
-  (DGR-007 files moved aside) gives the **identical** 13-failure set with `733
-  passed` (exactly −22), so this story introduces no new failures.
-- **Native C++ / CTest / llama.cpp patch stack** — **not touched by this story.**
-  The KV context contract is delivered at the Python manager level with a numpy
-  parity + isolation proof; the equivalent native layer-filtered KV / session
-  mapping is wired when the standalone C++ worker exists in DGR-008. No native
-  code, CMake, or llama.cpp patch was modified, so those gates are N/A here (same
-  as DGR-005/006).
-
-## Commands and real results
-
-```bash
-VP=/run/media/popov/d/DEV/repos/d-popov.com/AI/.venv/bin/python
-
-$VP -m pytest -q tests/test_hot_kv_state.py
-# -> 22 passed in ~0.3s
-
-$VP -m compileall -q packages tests
-# -> exit 0
-
-git diff --check
-# -> exit 0
-
-$VP -m pytest -q tests/test_boundary_adapter.py tests/test_gguf_ownership.py
-# -> 25 passed
-
-$VP -m pytest -q -rfE
-# -> 13 failed, 755 passed, 14 skipped in 254.50s
-
-# Clean-tree reproduction (DGR-007 files moved aside)
-mv packages/node/meshnet_node/hot_kv_state.py /tmp/ && mv tests/test_hot_kv_state.py /tmp/
-$VP -m pytest -q -rfE
-# -> 13 failed, 733 passed, 14 skipped in 252.12s  (identical FAILED set; passed -22)
-```
-
-`commands.txt` beside this README captures the exact commands.
-
-## Pre-existing unrelated failures (full-suite)
-
-`pytest -q -rfE` on `ralph/distributed-gguf-runtime` reports 13 pre-existing
-failures (and, in this run, 0 errors — the earlier DGR-005/006-era
-`test_native_shard_protocol.py` protobuf errors no longer appear in this
-environment). None touch the KV manager. Moving the two DGR-007 files aside and
-re-running yields the **byte-identical** 13-`FAILED` set (only the passed count
-drops by exactly 22). The exact set (all tracker/routing/benchmark/toploc/doctor,
-i.e. socket-bind / control-plane env, not KV):
-
-```
-tests/test_dynamic_routing.py::test_admin_can_replace_a_served_model_and_release_it
-tests/test_manual_route_benchmark.py::test_benchmark_records_one_and_two_node_routes
-tests/test_manual_route_benchmark.py::test_clients_without_route_are_unaffected
-tests/test_manual_route_benchmark.py::test_invalid_route_shape_is_400
-tests/test_manual_route_benchmark.py::test_pinned_route_uses_named_node
-tests/test_manual_route_benchmark.py::test_unknown_route_node_is_400
-tests/test_node_doctor.py::test_cli_doctor_flags_select_what_is_validated
-tests/test_toploc_calibration_dispatch.py::test_calibration_run_dispatches_only_solo_capable_nodes
-tests/test_toploc_calibration_dispatch.py::test_calibration_run_node_without_commitment_endpoint_is_skipped_not_failed
-tests/test_toploc_calibration_dispatch.py::test_calibration_run_persists_corpus_and_results_endpoint_reports_it
-tests/test_tracker_capability_admission.py::test_an_enforcing_tracker_never_routes_a_node_whose_proof_does_not_cover_it[invalid]
-tests/test_tracker_routing.py::test_shard_heal_cycle_surviving_node_covers_dead_peers_gap
-tests/test_tracker_routing.py::test_torch_node_applies_tracker_load_shard_directive
-```
-
-## Limitations and deferred work
-
-- **Numpy reference, not real weights.** The parity + isolation gate uses a
-  deterministic numpy KV-cached dense-Llama, not a downloaded GGUF/safetensors
-  model. Real-model concurrent KV isolation on a downloaded dense-Llama (CPU/ROCm)
-  belongs to DGR-010/DGR-012 with `MESHNET_ENABLE_REAL_INFERENCE_TESTS=1` and
-  `.venv-rocm`.
-- **Manager-owned storage, native mapping deferred.** The KV bytes are numpy
-  arrays managed in-process. The llama.cpp expression (a filtered llama sequence
-  per `(session, epoch)` over owned layers) is implemented in the standalone
-  worker (DGR-008) against this same manager contract; no native code was touched.
-- **Continuous batching is DGR-012.** This story delivers *isolation* and bounded
-  lifecycle for concurrent sessions; continuous batching of compatible active
-  sessions inside a node (decision #9) is DGR-012 and builds on this manager.
-- **Greedy-only sampling.** Reuses the DGR-006 `SamplingContract` (greedy
-  certified). Stochastic sampling is out of scope for the deterministic gate.
-- **Coexists with legacy `SessionCacheStore`.** The older AH-25
-  `model_backend.SessionCacheStore` (session-id-only, opaque transformers cache,
-  HTTP path) is untouched. `HotKvStateManager` is the native-runtime-aligned
-  successor: it adds route-epoch keying, owned-layer allocation, recipe-fingerprint
-  rejection, and a byte budget. DGR-008/009 wire the native worker to
-  `HotKvStateManager`, not `SessionCacheStore`.
-
-## Compatibility / migration notes
-
-- `KvCacheRecipe.fingerprint()` canonicalizes the architecture (via
-  `certified_architecture`), so `llama` / `LlamaForCausalLM` map to the same
-  recipe; it aligns field-for-field with the DGR-003 `RuntimeRecipeIdentity`
-  compatibility discipline and reuses `runtime_recipe.compatibility_fingerprint`.
-- `CacheMiss` is a value (not an exception) so it can be serialized into the
-  DGR-002 native protocol's cache expectation/result field; `resolve()` returns it,
-  `get()` raises `KvCacheMissError` wrapping it.
-- The manager takes an injectable `clock` for deterministic TTL tests; production
-  defaults to `time.monotonic`.
-
-## Handoff for dependent stories
-
-- **DGR-008 (C++ gRPC worker):** implement the servicer's KV path against
-  `HotKvStateManager`. Map each `(Route Session ID, route epoch)` to a filtered
-  llama sequence over owned layers; on decode, read the sequence's cached K/V,
-  compute the new position-encoded K/V, and commit via `append` (honour the byte
-  budget and return an explicit `CacheMiss` on eviction). Enforce
-  `KvCacheRecipe.is_compatible` before activation and reject stale epochs.
-- **DGR-009 (Meshnet integration):** the route epoch the tracker assigns is the
-  `route_epoch` key; carry the `CacheMiss` reason back to the head so it re-prefills
-  from token zero on eviction/restart.
-- **DGR-012 (continuous batching):** batch compatible active sessions whose
-  `KvCacheRecipe` fingerprints match; each session keeps its own `SessionCache`, so
-  batching is a scheduling concern layered over this isolation, not a change to it.
-- **DGR-013 (failure/cancel matrix):** `release` + the budget-return assertion here
-  is the unit-level basis for the resource-cleanup matrix.

.scratch/distributed-gguf-runtime/evidence/DGR-007/commands.txt

@@ -1,31 +0,0 @@
-# DGR-007 — exact commands (run from the worktree root).
-# Python: /run/media/popov/d/DEV/repos/d-popov.com/AI/.venv (Python 3.14.6, numpy 2.4.4).
-# Root conftest.py adds packages/* to sys.path, so `meshnet_node` imports work.
-
-VP=/run/media/popov/d/DEV/repos/d-popov.com/AI/.venv/bin/python
-
-# Targeted tests for this story.
-$VP -m pytest -q tests/test_hot_kv_state.py
-# -> 22 passed
-
-# Python compile check for the changed packages/tests.
-$VP -m compileall -q packages tests
-# -> exit 0
-
-# Diff hygiene.
-git diff --check
-# -> exit 0
-
-# Dependency (DGR-006) + range-ownership (DGR-005) tests still green.
-$VP -m pytest -q tests/test_boundary_adapter.py tests/test_gguf_ownership.py
-# -> 25 passed
-
-# Full deterministic suite (with DGR-007 files present).
-$VP -m pytest -q -rfE
-# -> see README (pre-existing unrelated failure set, +22 passed vs baseline)
-
-# Clean-tree reproduction (DGR-007 files moved aside).
-mv packages/node/meshnet_node/hot_kv_state.py /tmp/ && mv tests/test_hot_kv_state.py /tmp/
-$VP -m pytest -q -rfE
-# -> identical failure/error set, passed count drops by exactly 22
-mv /tmp/hot_kv_state.py packages/node/meshnet_node/ && mv /tmp/test_hot_kv_state.py tests/

.scratch/distributed-gguf-runtime/evidence/DGR-007/results.json

@@ -1,47 +0,0 @@
-{
-  "task_id": "DGR-007",
-  "title": "Add isolated concurrent local Hot KV State",
-  "status": "done",
-  "date": "2026-07-15",
-  "evidence_kind": "synthetic-unit",
-  "python": "/run/media/popov/d/DEV/repos/d-popov.com/AI/.venv (Python 3.14.6, numpy 2.4.4)",
-  "files_changed": [
-    "packages/node/meshnet_node/hot_kv_state.py",
-    "tests/test_hot_kv_state.py"
-  ],
-  "gates": {
-    "targeted_pytest": {"command": "pytest -q tests/test_hot_kv_state.py", "result": "22 passed"},
-    "compileall": {"command": "python -m compileall -q packages tests", "exit": 0},
-    "git_diff_check": {"command": "git diff --check", "exit": 0},
-    "dependency_tests": {"command": "pytest -q tests/test_boundary_adapter.py tests/test_gguf_ownership.py", "result": "25 passed"},
-    "full_suite_with_files": {"command": "pytest -q -rfE", "result": "13 failed, 755 passed, 14 skipped", "seconds": 254.50},
-    "full_suite_clean_tree": {"command": "pytest -q -rfE (DGR-007 files moved aside)", "result": "13 failed, 733 passed, 14 skipped", "seconds": 252.12}
-  },
-  "no_new_failures": true,
-  "failure_set_identical": true,
-  "passed_delta": 22,
-  "preexisting_failures": [
-    "tests/test_dynamic_routing.py::test_admin_can_replace_a_served_model_and_release_it",
-    "tests/test_manual_route_benchmark.py::test_benchmark_records_one_and_two_node_routes",
-    "tests/test_manual_route_benchmark.py::test_clients_without_route_are_unaffected",
-    "tests/test_manual_route_benchmark.py::test_invalid_route_shape_is_400",
-    "tests/test_manual_route_benchmark.py::test_pinned_route_uses_named_node",
-    "tests/test_manual_route_benchmark.py::test_unknown_route_node_is_400",
-    "tests/test_node_doctor.py::test_cli_doctor_flags_select_what_is_validated",
-    "tests/test_toploc_calibration_dispatch.py::test_calibration_run_dispatches_only_solo_capable_nodes",
-    "tests/test_toploc_calibration_dispatch.py::test_calibration_run_node_without_commitment_endpoint_is_skipped_not_failed",
-    "tests/test_toploc_calibration_dispatch.py::test_calibration_run_persists_corpus_and_results_endpoint_reports_it",
-    "tests/test_tracker_capability_admission.py::test_an_enforcing_tracker_never_routes_a_node_whose_proof_does_not_cover_it[invalid]",
-    "tests/test_tracker_routing.py::test_shard_heal_cycle_surviving_node_covers_dead_peers_gap",
-    "tests/test_tracker_routing.py::test_torch_node_applies_tracker_load_shard_directive"
-  ],
-  "native_gates_touched": false,
-  "acceptance": {
-    "session_epoch_isolated_context": true,
-    "kv_only_owned_layers": true,
-    "prefill_decode_truncate_release_ttl_lru_cachemiss": true,
-    "reject_stale_epoch_and_incompatible_recipe": true,
-    "four_concurrent_sessions_no_crosstalk": true,
-    "release_leaves_others_and_returns_memory": true
-  }
-}

.scratch/distributed-gguf-runtime/evidence/DGR-009/README.md

@@ -1,83 +0,0 @@
-# DGR-009 — Integrate the native worker with Meshnet: evidence
-
-Status: done
-Date: 2026-07-15
-Evidence kind: **python-unit + repo-hygiene**. No model download, no GPU, no API
-credit.
-
-## Summary
-
-Implemented the Meshnet-facing GGUF backend seam and recipe gating needed for
-the native worker path:
-
-- Added `GgufNodeBackend`, a backend-shaped adapter that lets the existing node
-  HTTP/control-plane code serve GGUF-backed shards without changing the
-  Transformers/Torch path for the default recipes.
-- Added `llama-cpp-native` to the recipe manifest and gated startup so only
-  recipes with `backend_id == "llama.cpp"` build the GGUF backend.
-- Preserved the existing registration/admission flow by carrying the validated
-  capability report and proof shard through registration.
-- Added unit coverage for the GGUF backend seam and for recipe-gated startup.
-- Fixed the explicit-shard startup path so the legacy Torch tests that use an
-  opaque stub model still pass without requiring HuggingFace config discovery.
-
-## Files changed
-
-- `packages/node/meshnet_node/gguf_backend.py` - new GGUF backend adapter and
-  worker-transport boundary.
-- `packages/node/meshnet_node/startup.py` - recipe-gated GGUF backend injection
-  and explicit-shard startup fix.
-- `packages/node/meshnet_node/recipes.json` - added `llama-cpp-native`.
-- `tests/test_gguf_backend.py` - backend delegation and recipe-selection tests.
-- `.ralph-tui/progress.md` - appended DGR-009 progress note.
-- `.scratch/distributed-gguf-runtime/issues/09-integrate-the-native-worker-with-meshnet.md`
-  - marked `Status: done`.
-
-## Commands and real results
-
-```bash
-python -m pytest -q tests/test_gguf_backend.py
-# -> 2 passed in 0.05s
-
-python -m pytest -q tests/test_node_admission.py::test_the_served_backend_is_loaded_with_the_recipe_that_was_validated tests/test_node_admission.py::test_backend_validation_failure_registers_nothing
-# -> 2 passed in 0.07s
-
-python -m compileall -q packages tests
-# -> exit 0
-
-git diff --check
-# -> exit 0
-
-python -m pytest -q
-# -> 222 failed, 463 passed, 13 skipped, 86 errors in 135.65s
-```
-
-## Limitations
-
-- `python -m pytest -q` is still not clean in this sandbox. The dominant
-  failures are tracker/control-plane socket `PermissionError: [Errno 1]
-  Operation not permitted` and a native protocol import failure caused by a
-  protobuf runtime mismatch (`gencode 7.35.0` vs runtime `6.33.6`).
-- `tests/test_native_shard_protocol.py` currently fails for the same protobuf
-  runtime mismatch in this environment.
-- `DGR-008` evidence was not present in the tree, so the dependency behavior was
-  verified by reading the live code and exercising the Python seam instead of
-  relying on a missing README.
-
-## Compatibility notes
-
-- The default Torch path remains intact; GGUF backend selection is explicit and
-  recipe-gated.
-- `TorchNodeServer` already accepts an injected backend object, so the control
-  plane stays Meshnet-owned.
-- The GGUF adapter currently establishes the seam for the native worker
-  transport; the compiled worker remains the owner of the gRPC protocol details.
-
-## Dependent-story handoff
-
-- DGR-008 should continue to own the native worker implementation and the
-  versioned gRPC frame handling behind `MESHNET_NATIVE_WORKER_URL`.
-- DGR-010 / DGR-012 can build on this seam without changing the control plane:
-  the recipe-gated backend and validated capability report are already carried
-  through startup.
-

.scratch/distributed-gguf-runtime/evidence/DGR-010/BLOCKED.md

@@ -1,58 +0,0 @@
-# DGR-010 — Blocked handoff
-
-Status: blocked
-Date: 2026-07-15
-
-## Blocker
-
-I verified the local workspace and mounted-drive model storage, but there is no
-certified dense-Llama artifact available on this machine to run the required
-real-model two-process acceptance.
-
-What I found:
-
-- `/run/media/popov/d/DEV/models` contains Qwen artifacts and caches, but no
-  dense-Llama model snapshot or GGUF artifact.
-- `/run/media/popov/d/DEV/llamacpp/llama.cpp/models` contains only vocab GGUFs,
-  not a certified dense-Llama model.
-- The existing code paths for real startup, GGUF backend selection, Hot KV
-  isolation, and benchmark reporting are present and readable, but the actual
-  DGR-010 acceptance run needs a certified dense-Llama artifact from mounted
-  storage to satisfy the story contract.
-
-## Verified current state
-
-- DGR-009 evidence was read and verified as the dependency handoff.
-- `packages/node/meshnet_node/startup.py` already gates backend selection by
-  recipe and can load either the Torch path or the explicit GGUF seam.
-- `packages/node/meshnet_node/hot_kv_state.py`, `boundary_adapter.py`, and
-  `gguf_ownership.py` already provide the isolation/parity seams that DGR-010
-  would exercise.
-- The repo has no existing `evidence/DGR-010/README.md` yet, which is expected
-  because the story has not been completed.
-
-## Commands run
-
-```bash
-sed -n '1,260p' .scratch/distributed-gguf-runtime/RALPH-CONTEXT.md
-sed -n '1,260p' .scratch/distributed-gguf-runtime/issues/10-pass-local-real-model-two-process-acceptance.md
-sed -n '1,260p' .scratch/distributed-gguf-runtime/evidence/DGR-009/README.md
-git status --short
-find /run/media/popov/d/DEV -type f \( -name '*.gguf' -o -name '*.safetensors' -o -name 'config.json' \) | rg -i 'llama|tinyllama|meta-llama|hf-internal-testing|qwen'
-```
-
-## Next step to unblock
-
-Provide or mount a certified dense-Llama artifact on the configured mounted
-drive storage, then rerun the DGR-010 acceptance path with
-`MESHNET_ENABLE_REAL_INFERENCE_TESTS=1`.
-
-## Continuation note
-
-Once the artifact exists, the next iteration should:
-
-1. Run the two local worker processes against the certified dense-Llama shard
-   ranges.
-2. Capture parity, concurrency, memory, and failure metrics.
-3. Write `evidence/DGR-010/README.md` with the real results and then update the
-   issue status.

.scratch/distributed-gguf-runtime/evidence/DGR-011/BLOCKED.md

@@ -1,70 +0,0 @@
-# DGR-011 — Blocked handoff
-
-Status: blocked
-Date: 2026-07-15
-
-## Blocker
-
-This story cannot be completed in the current workspace state because its
-mandatory dependency, DGR-010, is still not passed.
-
-Verified blockers:
-
-- `.scratch/distributed-gguf-runtime/prd.json` still marks `DGR-010` and
-  `DGR-011` with `"passes": false`.
-- `.scratch/distributed-gguf-runtime/evidence/DGR-010/README.md` does not
-  exist, and the only DGR-010 evidence artifact present is
-  `.scratch/distributed-gguf-runtime/evidence/DGR-010/BLOCKED.md`.
-- Mounted storage search found Qwen model artifacts and llama.cpp vocab files,
-  but no certified dense-Llama GGUF artifact suitable for the required real
-  acceptance run.
-
-## Verified current state
-
-- The repo already contains the Meshnet-facing GGUF backend seam and the
-  recipe-gated startup path from DGR-009.
-- The architecture and Ralph context require real-model execution for this
-  story, not synthetic workers or unit-only coverage.
-- The current environment does not expose the dense-Llama artifact required to
-  run the prerequisite local real-model acceptance, so the two-machine route
-  cannot be proven end to end.
-
-## Commands run
-
-```bash
-sed -n '1,260p' .scratch/distributed-gguf-runtime/RALPH-CONTEXT.md
-sed -n '1,260p' .scratch/distributed-gguf-runtime/issues/11-pass-a-real-heterogeneous-two-machine-route.md
-sed -n '1,260p' .ralph-tui/progress.md
-sed -n '1,240p' .scratch/distributed-gguf-runtime/evidence/DGR-010/BLOCKED.md
-sed -n '1,220p' CONTEXT.md
-sed -n '1,260p' docs/adr/0024-distributed-gguf-runtime.md
-sed -n '282,350p' .scratch/distributed-gguf-runtime/prd.json
-find /run/media/popov/d/DEV/models -maxdepth 3 \( -name '*.gguf' -o -name 'config.json' -o -name '*.safetensors' \)
-find /run/media/popov/d/DEV/llamacpp/llama.cpp/models /run/media/popov/d/DEV/models -maxdepth 4 \( -iname '*llama*' -o -iname '*dense*' -o -iname '*qwen*' -o -name 'config.json' -o -name '*.gguf' \)
-```
-
-## Known limitations
-
-- No certified dense-Llama artifact is available on mounted storage in this
-  workspace.
-- No real two-machine execution was possible, so there are no real route,
-  hardware, backend, or drift metrics to record for this story.
-- The story remains blocked until DGR-010 is completed with a real-model
-  evidence README and a confirmed dense-Llama artifact on mounted storage.
-
-## Compatibility notes
-
-- DGR-009's recipe-gated GGUF backend seam is present and can be reused.
-- The acceptance path for this story still requires the upstream real-model
-  evidence from DGR-010 before any heterogeneous two-machine route can be
-  claimed.
-
-## Dependent-story handoff
-
-- Finish DGR-010 first, including its real-model evidence README and
-  acceptance run.
-- Once DGR-010 passes, rerun the two-machine acceptance against the same
-  certified dense-Llama artifact, then record the two-host hardware/network
-  manifest, route, commands, and raw metrics in `evidence/DGR-011/README.md`.
-- Do not update the issue to `Status: done` until the real two-machine route
-  has been executed and recorded.

.scratch/distributed-gguf-runtime/evidence/DGR-012/README.md

@@ -1,220 +0,0 @@
-# DGR-012 — Continuous batching and bounded admission: evidence
-
-Status: done
-Date: 2026-07-16
-Evidence kind: **synthetic-unit** (pure-numpy KV-cached dense-Llama reference +
-node-local continuous-batching scheduler). No model download, no GPU, no torch,
-no network, no API credit.
-
-## Summary
-
-Implemented the node-local scheduler that turns concurrent Route Sessions into
-llama.cpp-style continuous batches while bounding admission (RALPH runtime
-decision #9, ADR-0024). It sits **on top of** the DGR-007 Hot KV State manager —
-batching is a scheduling concern layered over the existing per-`(session, epoch)`
-KV isolation, not a new control plane or a change to the KV contract.
-
-- **Bounded admission (`NodeBudget` + `submit`).** A new session is admitted only
-  if it fits four budgets: resident **weight** footprint (reported), **KV** byte
-  budget (a session must be able to hold its *whole* generation, prompt + new
-  tokens, on its own), **scratch** (per-active-session activation buffers, capped
-  by a total scratch envelope), and the bounded **queue**. Anything that cannot
-  fit is rejected up front with an explicit `AdmissionReason`
-  (`REJECTED_KV_BUDGET` / `REJECTED_SCRATCH_BUDGET` / `REJECTED_DUPLICATE`);
-  anything that fits but has no free slot waits in the bounded queue; a **full
-  queue is refused** (`REJECTED_QUEUE_FULL`) — that refusal is the backpressure
-  signal.
-- **Continuous batching (`ContinuousBatchScheduler` + `KvBatchEngine`).** Every
-  tick, all currently-decoding sessions contribute their single next token to one
-  batch (bounded by `max_batch_size`); the engine runs the batch once. Each
-  session keeps its own position and appends its own sampled token via its own
-  `SessionCache`, so batching never mixes outputs. `KvBatchEngine` adapts the
-  DGR-007 `KvBoundaryAdapter`, so the batch runs against the *real* KV isolation
-  path; the pinned llama.cpp worker (DGR-008) implements the same
-  `recipe_fingerprint`/`prefill`/`decode_batch`/`release` contract where a batch
-  becomes one `llama_decode` over several sequences.
-- **Prefill does not starve decode.** The scheduling policy is explicit and fixed:
-  **decode first, then bounded prefill.** In-flight decodes always run before any
-  new prompt is prefilled, and prefill work per tick is capped
-  (`max_prefill_tokens_per_tick`, always allowing at least one so a single large
-  prompt still progresses). A burst of new sessions cannot stall generations
-  already in flight.
-- **Bounded memory / backpressure.** KV growth is bounded by the manager byte
-  budget; queued activations are bounded by `max_queue_depth` and the scratch
-  envelope; completed sessions release their KV so total KV returns to zero.
-- **Capability telemetry (`SchedulerTelemetry`).** Reports active sessions, queue
-  depth, batch occupancy (last/avg/max), KV pressure (bytes/budget), scratch
-  pressure, prefill/decode token totals **and rates**, and rejected admissions
-  (total + by reason). All JSON-safe.
-- **Concurrency 1/2/4/8 sweep (`run_concurrency_sweep`).** Runs the same eight
-  jobs at each level against a fresh KV manager and proves (a) **no cross-session
-  corruption** — every level yields byte-identical per-session tokens as the
-  serialized concurrency-1 reference — and (b) **saturation** — average batch
-  occupancy rises and total ticks fall as concurrency increases, until occupancy
-  plateaus.
-
-No existing runtime code was modified — this story is purely additive (one new
-module + one new test module + evidence).
-
-## Files changed (all new)
-
-- `packages/node/meshnet_node/batch_scheduler.py` — the scheduler:
-  - `NodeBudget` — weight/KV/scratch/queue budgets + `max_batch_size` /
-    `max_prefill_tokens_per_tick` scheduling bounds, with derived
-    `effective_active_cap` (tighter of active-slot and scratch caps).
-  - `AdmissionReason` / `AdmissionDecision` — structured admit/queue/reject.
-  - `GenerationRequest` / `DecodeItem` / `StepResult` — job + engine I/O values.
-  - `KvBatchEngine` — adapts a full-shard `KvBoundaryAdapter` to the batch-engine
-    contract (rejects a partial head/tail-only range).
-  - `SchedulerTelemetry` — the bounded capability snapshot.
-  - `ContinuousBatchScheduler` — thread-safe `submit` / `run_tick` /
-    `run_to_completion` / `telemetry`, decode-first-then-bounded-prefill policy.
-  - `run_concurrency_sweep` / `ConcurrencyResult` / `ConcurrencySweep` — the
-    deterministic 1/2/4/8 saturation report + corruption check.
-- `tests/test_batch_scheduler.py` — 16 tests (see below); reuses the DGR-007
-  numpy dense-Llama reference via `from test_hot_kv_state import _KvDenseLlama,
-  _KvReferenceShard`.
-- `.scratch/distributed-gguf-runtime/evidence/DGR-012/` — this README,
-  `commands.txt`, `generate_evidence.py`, `results.json`.
-
-## Acceptance criteria → evidence
-
-- **Scheduler admits sessions against weight, KV, scratch, and queue budgets** —
-  `test_admission_respects_active_scratch_and_queue_budgets` (fill slots → queue →
-  reject full queue), `test_admission_rejects_a_session_that_cannot_fit_the_kv_budget`,
-  `test_admission_rejects_when_per_session_scratch_exceeds_budget`,
-  `test_duplicate_submission_is_rejected`,
-  `test_weight_budget_is_reported_in_telemetry`.
-- **Compatible decode steps form batches preserving per-session positions/outputs**
-  — `test_batched_decode_preserves_per_session_positions_and_outputs`
-  (`batch_occupancy_max == 4`, four divergent references each reproduced),
-  `test_positions_are_isolated_across_different_prompt_lengths` (prompt lengths 1/3/7).
-- **Prefill does not starve decode; policy and bounds explicit** —
-  `test_prefill_does_not_starve_in_flight_decode` (in-flight session decodes on
-  *every* tick during a 4-session prefill burst; ≤1 prefill/tick),
-  `test_decode_first_policy_is_explicit_in_a_single_tick`.
-- **Backpressure prevents unbounded queued activations or KV growth** —
-  `test_backpressure_signals_when_queue_full_then_recovers`,
-  `test_completed_sessions_release_kv_so_growth_is_bounded` (`kv_total_bytes == 0`
-  after completion).
-- **Capability telemetry reports all required signals** —
-  `test_telemetry_reports_every_required_signal` (asserts every key present;
-  deterministic rates under an injected clock).
-- **Concurrency 1/2/4/8 identifies saturation, no cross-session corruption** —
-  `test_concurrency_sweep_identifies_saturation_without_corruption`
-  (occupancy strictly ↑, ticks strictly ↓, tokens/tick ↑, `corruption_free`,
-  0 cache misses, saturation=8), `test_concurrency_sweep_saturates_below_max_when_load_is_small`.
-- **Engine/usage guards** — `test_kv_batch_engine_requires_a_full_shard`,
-  `test_run_to_completion_is_bounded_against_misconfiguration`.
-
-## Concurrency 1/2/4/8 sweep (real, deterministic — `results.json`)
-
-Eight sessions, prompt length 4, 8 new tokens each; fresh KV manager per level;
-budgets sized so KV never evicts (so the corruption check is unambiguous).
-
-| concurrency | ticks | avg batch occupancy | max occupancy | tokens/tick | peak KV bytes |
-|---|---|---|---|---|---|
-| 1 | 64 | 1.000 | 1 | 1.375 | 15360 |
-| 2 | 33 | 1.750 | 2 | 2.667 | 29184 |
-| 4 | 19 | 3.111 | 4 | 4.632 | 52224 |
-| 8 | 15 | 4.000 | 7 | 5.867 | 75264 |
-
-`saturation_concurrency = 8`, `corruption_free = True`, `cache_misses = 0`,
-`rejected_admissions = 0`. As concurrency rises, the scheduler packs more sessions
-per decode step (occupancy ↑) and finishes the same 56 decode + 32 prefill tokens
-in far fewer ticks (aggregate work/tick ↑) — the batching throughput property —
-while every per-session token stream stays byte-identical to the serialized
-reference (no cross-session corruption). Max occupancy is 7 (not 8) at level 8
-because the fairness policy prefills at most one new session per tick, so the last
-session begins decoding one tick later.
-
-## Commands and real results
-
-```bash
-VP=/run/media/popov/d/DEV/repos/d-popov.com/AI/.venv/bin/python
-
-$VP -m pytest -q tests/test_batch_scheduler.py
-# -> 16 passed
-
-$VP -m pytest -q tests/test_hot_kv_state.py       # dependency still green
-# -> 22 passed
-
-$VP -m compileall -q packages tests
-# -> exit 0
-
-git diff --check
-# -> exit 0
-
-$VP .scratch/distributed-gguf-runtime/evidence/DGR-012/generate_evidence.py
-# -> wrote results.json; saturation_concurrency=8 corruption_free=True
-
-$VP -m pytest -q -rfE -p no:cacheprovider
-# -> FULL_SUITE_RESULT_PLACEHOLDER
-```
-
-`commands.txt` beside this README captures the exact commands.
-
-## Full-suite baseline (pre-existing unrelated failures)
-
-FULL_SUITE_BASELINE_PLACEHOLDER
-
-## Limitations and deferred work
-
-- **Synthetic-unit, not real weights.** The scheduler is exercised against the
-  deterministic numpy KV-cached dense-Llama reference (the same one DGR-007 uses),
-  not a downloaded GGUF. This is required to keep the default gate deterministic,
-  download-free, and GPU-free. Real concurrent throughput on a downloaded
-  dense-Llama (CPU/ROCm) belongs to DGR-010 (blocked — no certified dense-Llama
-  artifact on this machine; see `evidence/DGR-010/BLOCKED.md`) and the final
-  comparison in DGR-014.
-- **Batching is a scheduling grouping in this reference.** `KvBatchEngine.decode_batch`
-  runs each batch member sequentially through the cached decode (each attends only
-  its own KV, exactly like an independent llama.cpp sequence). The pinned llama.cpp
-  worker (DGR-008) fuses the batch into one `llama_decode` graph; the scheduling
-  semantics — one batch per tick, isolated positions/outputs — are identical. The
-  numbers here are *scheduler* quantities (ticks, batch occupancy, tokens/tick)
-  that are real and deterministic; **actual kernel-level batching speedup is a
-  native-worker property and is NOT claimed here** (RALPH performance discipline:
-  no unmeasured speed claims). It is measured in DGR-008/DGR-010/DGR-014.
-- **Greedy sampling only.** Reuses the DGR-006 greedy `SamplingContract`. Greedy
-  over isolated per-session KV is order-independent, which is exactly why the
-  corruption check can assert byte-identical outputs across concurrency levels.
-  Stochastic sampling is out of scope for the deterministic gate.
-- **Single loaded shard / single recipe per scheduler.** The scheduler batches
-  compatible sessions of one loaded shard (one `recipe_fingerprint`), which is the
-  node-local case. Multi-range routes batch at the head node whose adapter owns the
-  final head; cross-node coordination stays in the Meshnet control plane.
-- **Native / llama.cpp gates N/A.** No native code, CMake, or llama.cpp patch was
-  touched (same as DGR-005/006/007), so those gates do not apply to this story.
-
-## Compatibility / migration notes
-
-- Purely additive: no existing module changed, so no behavior of the Torch/GGUF
-  backends, tracker, or KV manager is altered. The scheduler is opt-in — a server
-  constructs it around a `KvBatchEngine` when it wants continuous batching.
-- `SchedulerTelemetry.to_dict()` is JSON-safe and aligns with the capability-signal
-  vocabulary (active sessions, queue depth, batch occupancy, KV pressure,
-  prefill/decode rates, rejected admissions) that a node advertises upward; it can
-  be folded into the DGR-009 capability report / heartbeat without schema changes
-  here.
-- `AdmissionReason` values are stable strings suitable for the native protocol's
-  structured status / backpressure signalling.
-
-## Handoff for dependent stories
-
-- **DGR-008 (C++ gRPC worker):** implement the `BatchEngine` contract natively —
-  `decode_batch` becomes one `llama_decode` over the sessions' filtered sequences;
-  `prefill`/`release` map to the same KV manager operations. The scheduler,
-  admission budgets, fairness policy, and telemetry are unchanged; only the engine
-  swaps from numpy to llama.cpp.
-- **DGR-010 (local real two-process acceptance, blocked):** once a certified
-  dense-Llama artifact is mounted, drive `run_concurrency_sweep` (or the scheduler
-  directly) with a real `KvBatchEngine` over the GGUF backend to produce
-  real-hardware occupancy/throughput/KV-pressure numbers under
-  `MESHNET_ENABLE_REAL_INFERENCE_TESTS=1` / `.venv-rocm`.
-- **DGR-013 (failure/cancel/restart):** the `DoneReason.CACHE_MISS` path (a decode
-  whose KV was evicted marks the session done and re-prefillable) and the KV-release
-  on completion are the unit basis for the cancellation/cleanup matrix.
-- **DGR-014 (release gate):** feed the real-hardware sweep’s aggregate throughput
-  and saturation point into the immutable DGR-001 comparison; do not reuse these
-  synthetic numbers as a performance claim.

.scratch/distributed-gguf-runtime/evidence/DGR-012/commands.txt

@@ -1,24 +0,0 @@
-# DGR-012 — exact commands (run from the worktree root)
-# Default venv (Python 3.14); deterministic, download-free, GPU-free, API-credit-free.
-VP=/run/media/popov/d/DEV/repos/d-popov.com/AI/.venv/bin/python
-
-# Targeted story tests
-$VP -m pytest -q tests/test_batch_scheduler.py
-# -> 16 passed
-
-# Dependency (DGR-007) still green — scheduler builds on this KV manager
-$VP -m pytest -q tests/test_hot_kv_state.py
-# -> 22 passed
-
-# Python quality gates
-$VP -m compileall -q packages tests
-# -> exit 0
-git diff --check
-# -> exit 0
-
-# Regenerate the machine-readable concurrency-sweep evidence
-$VP .scratch/distributed-gguf-runtime/evidence/DGR-012/generate_evidence.py
-# -> writes results.json; saturation_concurrency=8 corruption_free=True
-
-# Full deterministic suite (records the pre-existing unrelated failure baseline)
-$VP -m pytest -q -rfE -p no:cacheprovider

.scratch/distributed-gguf-runtime/evidence/DGR-012/generate_evidence.py

@@ -1,117 +0,0 @@
-"""Regenerate the DGR-012 concurrency-sweep evidence artifact.
-
-Deterministic, download-free, GPU-free. Run from the repo root with the default
-venv so the worktree ``meshnet_node`` package and the DGR-007 numpy reference
-(``tests/test_hot_kv_state``) are importable:
-
-    python .scratch/distributed-gguf-runtime/evidence/DGR-012/generate_evidence.py
-
-Writes ``results.json`` beside this script.
-"""
-
-from __future__ import annotations
-
-import json
-import pathlib
-import sys
-
-_ROOT = pathlib.Path(__file__).resolve().parents[4]
-sys.path.insert(0, str(_ROOT / "packages" / "node"))
-sys.path.insert(0, str(_ROOT / "tests"))
-
-from test_hot_kv_state import _KvDenseLlama, _KvReferenceShard  # noqa: E402
-
-from meshnet_node.batch_scheduler import (  # noqa: E402
-    ContinuousBatchScheduler,
-    GenerationRequest,
-    KvBatchEngine,
-    NodeBudget,
-    run_concurrency_sweep,
-)
-from meshnet_node.hot_kv_state import (  # noqa: E402
-    HotKvStateManager,
-    KvBoundaryAdapter,
-    kv_recipe_for,
-)
-
-MODEL = _KvDenseLlama()
-
-
-def make_engine() -> KvBatchEngine:
-    shard = _KvReferenceShard(MODEL, 0, MODEL.n_layers - 1)
-    manager = HotKvStateManager(kv_recipe_for(shard))
-    return KvBatchEngine(KvBoundaryAdapter(shard, manager))
-
-
-def main() -> int:
-    prompts = {
-        "s0": [1, 2, 3, 4], "s1": [5, 6, 7, 8], "s2": [9, 10, 11, 12],
-        "s3": [13, 14, 15, 16], "s4": [17, 18, 19, 20], "s5": [21, 22, 23, 24],
-        "s6": [25, 26, 27, 28], "s7": [29, 30, 31, 32],
-    }
-    n_new = 8
-    requests = [
-        GenerationRequest(sid, 0, tuple(p), n_new) for sid, p in prompts.items()
-    ]
-    sweep = run_concurrency_sweep(
-        make_engine, requests, concurrency_levels=(1, 2, 4, 8)
-    )
-
-    # A representative telemetry snapshot mid-run at concurrency 4 (shows the live
-    # capability signals a node advertises upward).
-    engine = make_engine()
-    scheduler = ContinuousBatchScheduler(
-        engine,
-        NodeBudget(
-            max_active_sessions=4, max_batch_size=4, max_queue_depth=8,
-            scratch_bytes_per_session=1, scratch_budget_bytes=4,
-        ),
-    )
-    for request in requests:
-        scheduler.submit(request)
-    for _ in range(6):
-        scheduler.run_tick()
-    mid_run_telemetry = scheduler.telemetry().to_dict()
-
-    artifact = {
-        "schema_version": 1,
-        "evidence_kind": "synthetic-unit",
-        "model": {
-            "reference": "pure-numpy KV-cached dense-Llama (tests/test_hot_kv_state)",
-            "n_layers": MODEL.n_layers,
-            "hidden": MODEL.hidden,
-            "n_heads": MODEL.n_heads,
-            "vocab": MODEL.vocab,
-        },
-        "workload": {
-            "sessions": len(prompts),
-            "prompt_len": 4,
-            "max_new_tokens": n_new,
-        },
-        "concurrency_sweep": sweep.to_dict(),
-        "mid_run_telemetry_concurrency_4": mid_run_telemetry,
-    }
-
-    out = pathlib.Path(__file__).with_name("results.json")
-    out.write_text(json.dumps(artifact, indent=2, sort_keys=True) + "\n", encoding="utf-8")
-    print(f"wrote {out}")
-    print(
-        "saturation_concurrency=%d corruption_free=%s"
-        % (sweep.saturation_concurrency, sweep.corruption_free)
-    )
-    for result in sweep.results:
-        print(
-            "  c=%d ticks=%d avg_occ=%.3f tokens/tick=%.3f peak_kv=%dB"
-            % (
-                result.concurrency,
-                result.ticks,
-                result.avg_batch_occupancy,
-                result.tokens_per_tick,
-                result.peak_kv_bytes,
-            )
-        )
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

.scratch/distributed-gguf-runtime/evidence/DGR-012/results.json

@@ -1,179 +0,0 @@
-{
-  "concurrency_sweep": {
-    "corruption_free": true,
-    "reference_outputs": {
-      "s0": [
-        27,
-        8,
-        27,
-        8,
-        27,
-        8,
-        1,
-        1
-      ],
-      "s1": [
-        26,
-        39,
-        39,
-        39,
-        39,
-        3,
-        39,
-        39
-      ],
-      "s2": [
-        12,
-        12,
-        12,
-        12,
-        12,
-        12,
-        30,
-        12
-      ],
-      "s3": [
-        29,
-        41,
-        42,
-        47,
-        47,
-        42,
-        47,
-        42
-      ],
-      "s4": [
-        23,
-        11,
-        44,
-        29,
-        29,
-        29,
-        41,
-        29
-      ],
-      "s5": [
-        35,
-        11,
-        0,
-        1,
-        11,
-        0,
-        11,
-        15
-      ],
-      "s6": [
-        39,
-        39,
-        28,
-        39,
-        39,
-        39,
-        28,
-        28
-      ],
-      "s7": [
-        39,
-        39,
-        39,
-        39,
-        39,
-        39,
-        8,
-        47
-      ]
-    },
-    "results": [
-      {
-        "avg_batch_occupancy": 1.0,
-        "cache_misses": 0,
-        "concurrency": 1,
-        "decode_batches": 56,
-        "decode_tokens": 56,
-        "max_batch_occupancy": 1,
-        "peak_kv_bytes": 15360,
-        "prefill_tokens": 32,
-        "rejected_admissions": 0,
-        "ticks": 64,
-        "tokens_per_tick": 1.375
-      },
-      {
-        "avg_batch_occupancy": 1.75,
-        "cache_misses": 0,
-        "concurrency": 2,
-        "decode_batches": 32,
-        "decode_tokens": 56,
-        "max_batch_occupancy": 2,
-        "peak_kv_bytes": 29184,
-        "prefill_tokens": 32,
-        "rejected_admissions": 0,
-        "ticks": 33,
-        "tokens_per_tick": 2.6667
-      },
-      {
-        "avg_batch_occupancy": 3.1111,
-        "cache_misses": 0,
-        "concurrency": 4,
-        "decode_batches": 18,
-        "decode_tokens": 56,
-        "max_batch_occupancy": 4,
-        "peak_kv_bytes": 52224,
-        "prefill_tokens": 32,
-        "rejected_admissions": 0,
-        "ticks": 19,
-        "tokens_per_tick": 4.6316
-      },
-      {
-        "avg_batch_occupancy": 4.0,
-        "cache_misses": 0,
-        "concurrency": 8,
-        "decode_batches": 14,
-        "decode_tokens": 56,
-        "max_batch_occupancy": 7,
-        "peak_kv_bytes": 75264,
-        "prefill_tokens": 32,
-        "rejected_admissions": 0,
-        "ticks": 15,
-        "tokens_per_tick": 5.8667
-      }
-    ],
-    "saturation_concurrency": 8,
-    "schema_version": 1
-  },
-  "evidence_kind": "synthetic-unit",
-  "mid_run_telemetry_concurrency_4": {
-    "active_sessions": 4,
-    "batch_occupancy_avg": 4.0,
-    "batch_occupancy_last": 4,
-    "batch_occupancy_max": 4,
-    "completed_sessions": 0,
-    "decode_tokens_per_sec": 1637.355,
-    "decode_tokens_total": 20,
-    "kv_budget_bytes": 67108864,
-    "kv_pressure": 0.0008,
-    "kv_total_bytes": 55296,
-    "prefill_tokens_per_sec": 1309.884,
-    "prefill_tokens_total": 16,
-    "queue_depth": 4,
-    "rejected_admissions_total": 0,
-    "rejected_by_reason": {},
-    "scratch_budget_bytes": 4,
-    "scratch_pressure": 1.0,
-    "scratch_used_bytes": 4,
-    "ticks": 6,
-    "weight_bytes": 0
-  },
-  "model": {
-    "hidden": 32,
-    "n_heads": 4,
-    "n_layers": 6,
-    "reference": "pure-numpy KV-cached dense-Llama (tests/test_hot_kv_state)",
-    "vocab": 48
-  },
-  "schema_version": 1,
-  "workload": {
-    "max_new_tokens": 8,
-    "prompt_len": 4,
-    "sessions": 8
-  }
-}

.scratch/distributed-gguf-runtime/evidence/DGR-013/README.md

@@ -1,223 +0,0 @@
-# DGR-013 — Harden failure, cancellation, and restart semantics: evidence
-
-Status: done
-Date: 2026-07-16
-Evidence kind: **synthetic-unit** (pure-numpy KV-cached dense-Llama reference +
-node-local hardened stream). No model download, no GPU, no torch, no network, no
-API credit.
-
-## Summary
-
-Implemented bounded, explicit failure/cancellation/restart semantics for the
-per-Route-Session decode stream, layered on the DGR-007 Hot KV State manager
-(isolated `(session, epoch)` KV) and the DGR-012 continuous-batch scheduler. The
-goal (RALPH product objective) is that distributed speed never comes with hanging
-or corrupted generations: every blocked op is bounded, every cancel frees state,
-duplicate steps are idempotent, uncertain mutations are never silently replayed,
-alpha failover restarts from token zero, and billing distinguishes what actually
-completed.
-
-Everything runs against the same deterministic numpy dense-Llama reference the
-default gate uses (`tests/test_hot_kv_state.py::_KvDenseLlama` / `_KvReferenceShard`),
-so the whole failure matrix is deterministic, download-free, GPU-free, and
-API-credit-free while exercising the **real** KV isolation path
-(`KvBoundaryAdapter` + `HotKvStateManager`). The pinned llama.cpp worker (DGR-008)
-implements the identical adapter contract, so the semantics carry over to native
-execution unchanged.
-
-### What was built (`packages/node/meshnet_node/failure_semantics.py`, new)
-
-- **`DeadlineGuard` + `StreamTerminated`** — bounds every step against an absolute
-  deadline and a heartbeat-timeout on an injected clock. A reached deadline or a
-  lost heartbeat (peer health loss) raises `StreamTerminated(kind)` so a blocked
-  stream terminates instead of hanging. (**AC: deadlines/heartbeat terminate
-  blocked ops.**)
-- **`CancellationToken`, `ShardCancellationGroup`, `CancellationOutcome`** — one
-  cancel fans across **every** node-local Shard of a Route Session, releasing the
-  `(session, epoch)` KV on each shard's manager and invoking every queued-buffer
-  release callback (the pending activation bundles). Idempotent. The DGR-012
-  scheduler also gains a `cancel()` that drops queued/active work on this node and
-  frees its KV. (**AC: cancellation propagates across every Shard, releases KV +
-  queued buffers.**)
-- **`IdempotencyLedger`, `StepKey`, `StepDisposition`, `UncertainMutationError`** —
-  records each committed `(session, epoch, step)`; a duplicate delivery returns the
-  recorded token with no re-mutation. A step whose mutation outcome is *uncertain*
-  (worker died mid-step) is marked uncertain and can **never** be replayed
-  silently — `begin()` on an uncertain (or still in-flight) step raises
-  `UncertainMutationError`, forcing verify-or-restart. (**AC: duplicate steps
-  idempotent; uncertain mutations never replayed silently.**)
-- **`RestartController`** — alpha failover: opens the *next* route epoch, releases
-  every shard's prior-epoch KV, and `assert_fresh_start` fails closed if any shard
-  still holds new-epoch KV. The restart re-prefills the whole prompt from token
-  zero; the failed epoch becomes stale (KV manager rejects it). Unverified KV is
-  never migrated (RALPH runtime decision #14). (**AC: alpha failover restarts from
-  token zero rather than importing unverified KV.**)
-- **`WorkStatus`, `WorkRecord`, `WorkLedger`** — a typed per-attempt work record
-  with four distinct statuses: `completed`, `cancelled`, `failed`, `unverified`.
-  Only `completed` records are billable; cancelled/failed/unverified tokens are
-  recorded for observability but never charged. JSON-safe for the tracker billing
-  handoff (`packages/tracker/meshnet_tracker/billing.py` charges only completed,
-  verified work). (**AC: billing/work records distinguish completed/cancelled/
-  failed/unverified.**)
-- **`HardenedSessionRunner`** — composes all of the above to drive one session's
-  prefill+decode through the adapter under a deadline/heartbeat guard + cancel
-  token, records the typed outcome, and `run_with_failover` restarts a transient
-  failure from token zero on a fresh epoch.
-- **`FailureKind` + `classify_exception` + `work_status_for`** — stable-string
-  classification of worker death, stream reset, malformed bundle, stale epoch,
-  cache miss, deadline, heartbeat loss, and cancel, plus the failure→billing-status
-  mapping. Suitable for the native protocol's structured status.
-
-### Scheduler extension (`packages/node/meshnet_node/batch_scheduler.py`, DGR-012 file, additive)
-
-Purely additive so the DGR-012 gate stays green (16/16):
-- `DoneReason.CANCELLED` / `DoneReason.FAILED` terminal reasons.
-- `ContinuousBatchScheduler.cancel(session_id, *, reason)` — drops a queued
-  session from the bounded queue or releases an active session's KV, moving it to
-  the done set with a non-completed reason (never counted as completed work).
-- `SchedulerTelemetry.cancelled_sessions` / `failed_sessions` counters.
-
-## Files changed
-
-- `packages/node/meshnet_node/failure_semantics.py` — new module (the whole
-  failure/cancel/restart layer above).
-- `packages/node/meshnet_node/batch_scheduler.py` — additive `cancel()` + two
-  `DoneReason` members + two telemetry counters (DGR-012 file; its 16 tests still
-  pass unchanged).
-- `tests/test_failure_semantics.py` — new, 22 tests (matrix below); reuses the
-  DGR-007 numpy reference via `from test_hot_kv_state import _KvDenseLlama,
-  _KvReferenceShard`.
-- `.scratch/distributed-gguf-runtime/evidence/DGR-013/` — this README,
-  `commands.txt`, `generate_evidence.py`, `results.json`.
-- `.ralph-tui/progress.md` — appended the DGR-013 note.
-- `.scratch/distributed-gguf-runtime/issues/13-...md` — set `Status: done`.
-
-## Acceptance criteria → evidence
-
-| Criterion | Tests (`tests/test_failure_semantics.py`) |
-|---|---|
-| Deadlines/heartbeat loss terminate blocked stream ops | `test_deadline_terminates_a_blocked_stream_and_releases_kv`, `test_heartbeat_loss_terminates_a_blocked_stream`, `test_deadline_guard_reports_remaining_and_resets_on_heartbeat` |
-| Cancellation propagates across every Shard, releases KV + queued buffers | `test_cancellation_token_terminates_stream_and_releases_kv`, `test_shard_cancellation_group_releases_every_shard_and_queued_buffers`, `test_scheduler_cancel_drains_queue_and_releases_active_kv`, `test_scheduler_cancel_rejects_a_completed_reason` |
-| Duplicate steps idempotent; uncertain mutations never replayed silently | `test_duplicate_step_delivery_is_idempotent_no_remutation`, `test_idempotent_run_replays_tokens_without_advancing_kv`, `test_uncertain_mutation_is_never_replayed_silently`, `test_in_flight_duplicate_is_treated_as_uncertain` |
-| Alpha failover restarts from token zero, no unverified KV import | `test_alpha_failover_restarts_from_token_zero_and_completes`, `test_failover_refuses_to_import_unverified_kv`, `test_non_restartable_failure_is_not_retried` |
-| Worker death, stream reset, malformed bundle, stale epoch, cache miss | `test_worker_death_midstream_is_unverified_and_marks_step_uncertain`, `test_stream_reset_is_restartable_failure`, `test_malformed_bundle_is_classified_and_does_not_corrupt_kv`, `test_stale_epoch_reference_is_rejected_and_classified`, `test_cache_miss_midstream_is_restartable` |
-| Billing/work records distinguish completed/cancelled/failed/unverified | `test_work_ledger_distinguishes_all_four_statuses`, `test_work_status_and_classification_mapping`, plus the clean-run billability check `test_clean_run_matches_stateless_reference_and_is_billable` |
-
-## Failure matrix (real, deterministic — `results.json`)
-
-Generated by `generate_evidence.py` against the numpy dense-Llama (prompt `[7,3,9,1]`,
-8 new tokens):
-
-| scenario | status | failure_kind | tokens | restartable | KV released |
-|---|---|---|---|---|---|
-| clean | completed | — | 8 | — | (held, then reaped) |
-| deadline | failed | deadline-exceeded | 2 | no | yes |
-| heartbeat_loss | failed | heartbeat-lost | 3 | no | yes |
-| cancel | cancelled | cancelled | 3 | no | yes |
-| worker_death | unverified | worker-death | 3 | yes | yes |
-| stream_reset | failed | stream-reset | — | yes | yes |
-| stale_epoch | failed | stale-epoch | — | no | (never opened) |
-| cache_miss | failed | cache-miss | 4 | yes | (already evicted) |
-| alpha_failover | **completed** (epoch 1) | — | 8 | — | old epoch stale |
-
-Alpha failover: attempt 0 (epoch 0) dies mid-step → `unverified`; the controller
-advances to epoch 1, drops epoch-0 KV, and the restart re-prefills from token zero
-→ `completed`, reproducing the byte-identical stateless reference. The old epoch is
-now stale (a reference to it raises `StaleRouteEpochError`). Work ledger:
-`{completed: 2, cancelled: 1, failed: 0, unverified: 2}`, `billable_tokens = 16`
-(only the two completed streams — the failover restart and the clean run — are
-billed; the cancelled and the two unverified attempts are not).
-
-## Commands and real results
-
-See `commands.txt`. Key results:
-
-```
-tests/test_failure_semantics.py     -> 22 passed
-tests/test_batch_scheduler.py       -> 16 passed (DGR-012 unchanged)
-tests/test_hot_kv_state.py          -> 22 passed (DGR-007)
-tests/test_gguf_backend.py          ->  2 passed (DGR-009)
-python -m compileall -q packages tests -> exit 0
-git diff --check                       -> exit 0
-python -m pytest -q                    -> 16 failed, 792 passed, 14 skipped in 253.93s
-```
-
-## Full-suite baseline (pre-existing, unrelated failures)
-
-The 16 failures are **pre-existing and unrelated to DGR-013**. None import
-`failure_semantics` or `batch_scheduler`; they live in the tracker/control-plane,
-node-startup, doctor, calibration, and route-benchmark suites and fail on the
-model-download / control-plane / recipe-admission paths (e.g.
-`UnsupportedRecipeParam: worker_transport` from the DGR-009 native recipe against
-the Torch backend, and Torch/HF-model startup that this deterministic sandbox does
-not provide). Removing the two DGR-013 files and re-running the failing tests
-reproduces the identical failures (see `commands.txt`, 4-test spot check → same
-4 failures), so DGR-013 introduces no new failure.
-
-Exact failing set (16):
-
-```
-tests/test_dynamic_routing.py::test_admin_can_replace_a_served_model_and_release_it
-tests/test_manual_route_benchmark.py::test_pinned_route_uses_named_node
-tests/test_manual_route_benchmark.py::test_unknown_route_node_is_400
-tests/test_manual_route_benchmark.py::test_invalid_route_shape_is_400
-tests/test_manual_route_benchmark.py::test_clients_without_route_are_unaffected
-tests/test_manual_route_benchmark.py::test_benchmark_records_one_and_two_node_routes
-tests/test_node_doctor.py::test_the_shipped_recipes_are_all_applicable_by_the_backend
-tests/test_node_doctor.py::test_cli_doctor_flags_select_what_is_validated
-tests/test_node_startup.py::test_preset_model_with_hf_repo_loads_torch_backend
-tests/test_node_startup.py::test_real_model_startup_registers_downloaded_inventory_without_checksum
-tests/test_toploc_calibration_dispatch.py::test_calibration_run_dispatches_only_solo_capable_nodes
-tests/test_toploc_calibration_dispatch.py::test_calibration_run_persists_corpus_and_results_endpoint_reports_it
-tests/test_toploc_calibration_dispatch.py::test_calibration_run_node_without_commitment_endpoint_is_skipped_not_failed
-tests/test_tracker_capability_admission.py::test_an_enforcing_tracker_never_routes_a_node_whose_proof_does_not_cover_it[invalid]
-tests/test_tracker_routing.py::test_torch_node_applies_tracker_load_shard_directive
-tests/test_tracker_routing.py::test_shard_heal_cycle_surviving_node_covers_dead_peers_gap
-```
-
-## Limitations and deferred work
-
-- **Synthetic-unit, not real weights.** Semantics are exercised against the
-  deterministic numpy dense-Llama, not a downloaded GGUF, to keep the default gate
-  deterministic/download-free/GPU-free. Real worker-death/stream-reset behavior on
-  a live llama.cpp worker over gRPC belongs to DGR-008/DGR-010 (DGR-010 is blocked
-  — no certified dense-Llama artifact on this machine; see
-  `evidence/DGR-010/BLOCKED.md`).
-- **Single-node per-session stream.** `HardenedSessionRunner` drives one full-shard
-  session (the node-local case); multi-node cancellation is modelled by
-  `ShardCancellationGroup` fanning across each node's KV manager. The cross-node
-  propagation *transport* (cancel frames over gRPC/relay) is the native protocol's
-  job (DGR-002/008); this story owns the local release + record semantics the
-  transport triggers.
-- **Fault injection is deterministic.** Worker death is a shard that raises on the
-  Nth step; stream reset / deadline / heartbeat are injected via an explicit clock
-  and hook. This is what makes the matrix reproducible; live fault behavior is a
-  native/real-hardware property.
-- **Greedy sampling only.** Reuses the DGR-006 greedy `SamplingContract`; the
-  idempotent-replay equality check depends on order-independent greedy decode.
-- **Native / llama.cpp gates N/A.** No native code, CMake, or llama.cpp patch was
-  touched (same as DGR-005/006/007/012), so those gates do not apply.
-
-## Compatibility / migration notes
-
-- `failure_semantics.py` is a new, additive module — no existing behavior changes.
-- `batch_scheduler.py` changes are additive (new enum members, one method, two
-  telemetry fields); the DGR-012 contract and its 16 tests are unchanged.
-- `WorkRecord.to_dict()` / `WorkLedger.to_dict()` are JSON-safe and map cleanly to
-  the tracker `BillingLedger.charge_request` inputs: report `node_work` only for
-  `billable` (completed) records so cancelled/failed/unverified work is never
-  charged. `FailureKind` / `WorkStatus` are stable strings suitable for the native
-  protocol's structured status and the capability/heartbeat report.
-
-## Handoff for dependent stories
-
-- **DGR-008 (C++ gRPC worker):** implement the same contract natively — the worker
-  maps a transport deadline/heartbeat to `StreamTerminated`, a dropped stream to a
-  restartable failure, and a mid-`llama_decode` crash to an *uncertain* step
-  (mark-uncertain, never silent replay). `RestartController.failover` maps to
-  opening a fresh llama sequence under the new `(session, epoch)`; the failed
-  sequence's KV is dropped, never migrated.
-- **DGR-010/DGR-014 (real acceptance / release gate):** drive the same failure
-  scenarios against the live worker to produce real cleanup/latency numbers, and
-  feed the `WorkLedger` status split into the billing/attribution comparison —
-  only `completed` work is charged.

.scratch/distributed-gguf-runtime/evidence/DGR-013/commands.txt

@@ -1,36 +0,0 @@
-# DGR-013 — exact commands and real results (worktree venv)
-VP=/run/media/popov/d/DEV/repos/d-popov.com/AI/.venv/bin/python
-
-# Targeted story tests (this story)
-$VP -m pytest -q tests/test_failure_semantics.py
-# -> 22 passed
-
-# Dependency gates stay green
-$VP -m pytest -q tests/test_batch_scheduler.py        # DGR-012
-# -> 16 passed
-$VP -m pytest -q tests/test_hot_kv_state.py           # DGR-007
-# -> 22 passed
-$VP -m pytest -q tests/test_gguf_backend.py           # DGR-009
-# -> 2 passed
-
-# Quality gates
-$VP -m compileall -q packages tests
-# -> exit 0
-git diff --check
-# -> exit 0
-
-# Machine-readable evidence
-$VP .scratch/distributed-gguf-runtime/evidence/DGR-013/generate_evidence.py
-# -> wrote results.json; work statuses {'completed':2,'cancelled':1,'failed':0,'unverified':2} billable_tokens=16
-
-# Full deterministic suite
-$VP -m pytest -q -p no:cacheprovider
-# -> 16 failed, 792 passed, 14 skipped in 253.93s
-
-# Clean-tree reproduction of the 16 pre-existing failures (DGR-013 files removed)
-# rm packages/node/meshnet_node/failure_semantics.py tests/test_failure_semantics.py
-$VP -m pytest -q tests/test_dynamic_routing.py::test_admin_can_replace_a_served_model_and_release_it \
-  tests/test_node_doctor.py::test_the_shipped_recipes_are_all_applicable_by_the_backend \
-  tests/test_tracker_routing.py::test_torch_node_applies_tracker_load_shard_directive \
-  tests/test_node_startup.py::test_preset_model_with_hf_repo_loads_torch_backend
-# -> 4 failed (same failures reproduce without any DGR-013 change)

.scratch/distributed-gguf-runtime/evidence/DGR-013/generate_evidence.py

@@ -1,234 +0,0 @@
-#!/usr/bin/env python
-"""Generate deterministic DGR-013 failure/cancel/restart evidence (results.json).
-
-Runs the real hardened per-session stream (``HardenedSessionRunner`` over the
-DGR-007 ``KvBoundaryAdapter`` + ``HotKvStateManager``) through each failure mode
-with the same pure-numpy dense-Llama reference the default gate uses. No model
-download, no GPU, no torch, no network, no API credit.
-
-Run from the repo root with the worktree venv:
-
-    .venv/bin/python .scratch/distributed-gguf-runtime/evidence/DGR-013/generate_evidence.py
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import sys
-
-import numpy as np
-
-# Make the worktree packages and the DGR-007 numpy reference importable, exactly
-# as pytest's prepend-import + conftest do.
-ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", "..", ".."))
-sys.path.insert(0, os.path.join(ROOT, "packages", "node"))
-sys.path.insert(0, os.path.join(ROOT, "tests"))
-
-from meshnet_node.hot_kv_state import (  # noqa: E402
-    HotKvStateConfig,
-    HotKvStateManager,
-    KvBoundaryAdapter,
-    StaleRouteEpochError,
-    kv_recipe_for,
-)
-from meshnet_node.batch_scheduler import GenerationRequest  # noqa: E402
-from meshnet_node.failure_semantics import (  # noqa: E402
-    CancellationToken,
-    FailureKind,
-    HardenedSessionRunner,
-    RestartController,
-    StreamTerminated,
-    WorkLedger,
-    WorkStatus,
-)
-
-from test_hot_kv_state import _KvDenseLlama, _KvReferenceShard  # noqa: E402
-
-
-class _FaultyShard(_KvReferenceShard):
-    def __init__(self, model, start, end, *, fail_at_call=None):
-        super().__init__(model, start, end)
-        self._fail_at_call = fail_at_call
-        self.calls = 0
-
-    def run_layers_cached(self, hidden, *, positions, past_kv):
-        self.calls += 1
-        if self._fail_at_call is not None and self.calls == self._fail_at_call:
-            raise RuntimeError("worker died mid-step")
-        return super().run_layers_cached(hidden, positions=positions, past_kv=past_kv)
-
-
-class _Clock:
-    def __init__(self):
-        self.now = 0.0
-
-    def __call__(self):
-        return self.now
-
-    def advance(self, d):
-        self.now += d
-
-
-def _adapter(model, *, config=None, shard=None):
-    shard = shard or _KvReferenceShard(model, 0, model.n_layers - 1)
-    manager = HotKvStateManager(kv_recipe_for(shard), config=config)
-    return KvBoundaryAdapter(shard, manager)
-
-
-def _gen(sid, prompt, n, epoch=0):
-    return GenerationRequest(
-        session_id=sid, route_epoch=epoch,
-        prompt_token_ids=tuple(prompt), max_new_tokens=n,
-    )
-
-
-def _kv_released(manager, sid, epoch):
-    from meshnet_node.hot_kv_state import CacheMiss
-    return isinstance(manager.resolve(sid, epoch), CacheMiss)
-
-
-def main() -> None:
-    model = _KvDenseLlama()
-    prompt = [7, 3, 9, 1]
-    n_new = 8
-    ledger = WorkLedger()
-    scenarios = []
-
-    # 1. Clean baseline.
-    ad = _adapter(model)
-    r = HardenedSessionRunner(ad, work_ledger=ledger).run(_gen("clean", prompt, n_new))
-    scenarios.append({
-        "scenario": "clean",
-        "status": r.status.value,
-        "tokens": r.token_count,
-        "matches_reference": list(r.tokens) == model.stateless_greedy(prompt, n_new),
-        "kv_released": _kv_released(ad.manager, "clean", 0),
-    })
-
-    # 2. Deadline terminates a blocked stream.
-    clk = _Clock()
-    ad = _adapter(model)
-    r = HardenedSessionRunner(ad, clock=clk).run(
-        _gen("deadline", prompt, 50), deadline=3.0,
-        before_step=lambda _s: clk.advance(1.0),
-    )
-    scenarios.append({
-        "scenario": "deadline", "status": r.status.value,
-        "failure_kind": r.failure_kind.value, "tokens": r.token_count,
-        "kv_released": _kv_released(ad.manager, "deadline", 0),
-    })
-
-    # 3. Heartbeat/health loss terminates a blocked stream.
-    clk = _Clock()
-    ad = _adapter(model)
-    r = HardenedSessionRunner(ad, clock=clk).run(
-        _gen("heartbeat", prompt, 50), heartbeat_timeout=1.5,
-        heartbeat=lambda step: step < 2,
-        before_step=lambda _s: clk.advance(1.0),
-    )
-    scenarios.append({
-        "scenario": "heartbeat_loss", "status": r.status.value,
-        "failure_kind": r.failure_kind.value, "tokens": r.token_count,
-        "kv_released": _kv_released(ad.manager, "heartbeat", 0),
-    })
-
-    # 4. Explicit client cancellation releases KV.
-    ad = _adapter(model)
-    tok = CancellationToken()
-    r = HardenedSessionRunner(ad, work_ledger=ledger).run(
-        _gen("cancel", prompt, 50), cancel_token=tok,
-        before_step=lambda step: tok.cancel("client-hangup") if step == 3 else None,
-    )
-    scenarios.append({
-        "scenario": "cancel", "status": r.status.value,
-        "failure_kind": r.failure_kind.value, "tokens": r.token_count,
-        "kv_released": _kv_released(ad.manager, "cancel", 0),
-    })
-
-    # 5. Worker death mid-step -> unverified.
-    ad = _adapter(model, shard=_FaultyShard(model, 0, model.n_layers - 1, fail_at_call=4))
-    r = HardenedSessionRunner(ad, work_ledger=ledger).run(_gen("worker", prompt, n_new))
-    scenarios.append({
-        "scenario": "worker_death", "status": r.status.value,
-        "failure_kind": r.failure_kind.value, "tokens": r.token_count,
-        "restartable": r.restartable, "kv_released": _kv_released(ad.manager, "worker", 0),
-    })
-
-    # 6. Stream reset -> failed, restartable.
-    ad = _adapter(model)
-    def reset(step):
-        if step == 2:
-            raise StreamTerminated(FailureKind.STREAM_RESET, "peer reset")
-    r = HardenedSessionRunner(ad).run(_gen("reset", prompt, n_new), before_step=reset)
-    scenarios.append({
-        "scenario": "stream_reset", "status": r.status.value,
-        "failure_kind": r.failure_kind.value, "restartable": r.restartable,
-    })
-
-    # 7. Stale epoch -> failed.
-    ad = _adapter(model)
-    ad.manager.open("stale", 5)
-    r = HardenedSessionRunner(ad).run(_gen("stale", prompt, n_new, epoch=3))
-    scenarios.append({
-        "scenario": "stale_epoch", "status": r.status.value,
-        "failure_kind": r.failure_kind.value,
-    })
-
-    # 8. Cache miss mid-stream -> restartable.
-    ad = _adapter(model)
-    mgr = ad.manager
-    r = HardenedSessionRunner(ad).run(
-        _gen("miss", prompt, 12),
-        before_step=lambda step: mgr.release("miss", 0) if step == 4 else None,
-    )
-    scenarios.append({
-        "scenario": "cache_miss", "status": r.status.value,
-        "failure_kind": r.failure_kind.value, "tokens": r.token_count,
-        "restartable": r.restartable,
-    })
-
-    # 9. Alpha failover: restart from token zero, no unverified KV import.
-    faulty = _FaultyShard(model, 0, model.n_layers - 1, fail_at_call=3)
-    ad = _adapter(model, shard=faulty)
-    runner = HardenedSessionRunner(ad, work_ledger=ledger)
-    controller = RestartController([ad.manager])
-    fo = runner.run_with_failover(_gen("failover", prompt, n_new, epoch=0), controller,
-                                  max_restarts=2)
-    old_epoch_stale = False
-    try:
-        ad.manager.resolve("failover", 0)
-    except StaleRouteEpochError:
-        old_epoch_stale = True
-    scenarios.append({
-        "scenario": "alpha_failover",
-        "final_status": fo.outcome.status.value,
-        "final_epoch": fo.outcome.route_epoch,
-        "restarts": fo.restarts,
-        "restarted_from_token_zero": list(fo.outcome.tokens) == model.stateless_greedy(prompt, n_new),
-        "old_epoch_stale": old_epoch_stale,
-        "attempt_statuses": [a.status.value for a in fo.attempts],
-    })
-
-    result = {
-        "schema_version": 1,
-        "evidence_kind": "synthetic-unit",
-        "model": {
-            "architecture": model.architecture_adapter,
-            "n_layers": model.n_layers, "vocab": model.vocab, "hidden": model.hidden,
-        },
-        "scenarios": scenarios,
-        "work_ledger": ledger.to_dict(),
-    }
-
-    out_path = os.path.join(os.path.dirname(__file__), "results.json")
-    with open(out_path, "w") as fh:
-        json.dump(result, fh, indent=2)
-        fh.write("\n")
-    counts = ledger.counts_by_status()
-    print(f"wrote {out_path}")
-    print(f"work statuses: {counts}  billable_tokens={ledger.billable_tokens()}")
-
-
-if __name__ == "__main__":
-    main()

.scratch/distributed-gguf-runtime/evidence/DGR-013/results.json

@@ -1,135 +0,0 @@
-{
-  "schema_version": 1,
-  "evidence_kind": "synthetic-unit",
-  "model": {
-    "architecture": "dense-llama",
-    "n_layers": 6,
-    "vocab": 48,
-    "hidden": 32
-  },
-  "scenarios": [
-    {
-      "scenario": "clean",
-      "status": "completed",
-      "tokens": 8,
-      "matches_reference": true,
-      "kv_released": false
-    },
-    {
-      "scenario": "deadline",
-      "status": "failed",
-      "failure_kind": "deadline-exceeded",
-      "tokens": 2,
-      "kv_released": true
-    },
-    {
-      "scenario": "heartbeat_loss",
-      "status": "failed",
-      "failure_kind": "heartbeat-lost",
-      "tokens": 3,
-      "kv_released": true
-    },
-    {
-      "scenario": "cancel",
-      "status": "cancelled",
-      "failure_kind": "cancelled",
-      "tokens": 3,
-      "kv_released": true
-    },
-    {
-      "scenario": "worker_death",
-      "status": "unverified",
-      "failure_kind": "worker-death",
-      "tokens": 3,
-      "restartable": true,
-      "kv_released": true
-    },
-    {
-      "scenario": "stream_reset",
-      "status": "failed",
-      "failure_kind": "stream-reset",
-      "restartable": true
-    },
-    {
-      "scenario": "stale_epoch",
-      "status": "failed",
-      "failure_kind": "stale-epoch"
-    },
-    {
-      "scenario": "cache_miss",
-      "status": "failed",
-      "failure_kind": "cache-miss",
-      "tokens": 4,
-      "restartable": true
-    },
-    {
-      "scenario": "alpha_failover",
-      "final_status": "completed",
-      "final_epoch": 1,
-      "restarts": 1,
-      "restarted_from_token_zero": true,
-      "old_epoch_stale": true,
-      "attempt_statuses": [
-        "unverified",
-        "completed"
-      ]
-    }
-  ],
-  "work_ledger": {
-    "schema_version": 1,
-    "records": [
-      {
-        "session_id": "clean",
-        "route_epoch": 0,
-        "status": "completed",
-        "tokens": 8,
-        "failure_kind": null,
-        "detail": "",
-        "billable": true
-      },
-      {
-        "session_id": "cancel",
-        "route_epoch": 0,
-        "status": "cancelled",
-        "tokens": 3,
-        "failure_kind": "cancelled",
-        "detail": "operation cancelled: client-hangup",
-        "billable": false
-      },
-      {
-        "session_id": "worker",
-        "route_epoch": 0,
-        "status": "unverified",
-        "tokens": 3,
-        "failure_kind": "worker-death",
-        "detail": "worker died mid-step",
-        "billable": false
-      },
-      {
-        "session_id": "failover",
-        "route_epoch": 0,
-        "status": "unverified",
-        "tokens": 2,
-        "failure_kind": "worker-death",
-        "detail": "worker died mid-step",
-        "billable": false
-      },
-      {
-        "session_id": "failover",
-        "route_epoch": 1,
-        "status": "completed",
-        "tokens": 8,
-        "failure_kind": null,
-        "detail": "",
-        "billable": true
-      }
-    ],
-    "counts_by_status": {
-      "completed": 2,
-      "cancelled": 1,
-      "failed": 0,
-      "unverified": 2
-    },
-    "billable_tokens": 16
-  }
-}

.scratch/distributed-gguf-runtime/evidence/DGR-014/BLOCKED.md

@@ -1,55 +0,0 @@
-# DGR-014 — Blocked handoff
-
-Status: blocked
-Date: 2026-07-16
-
-## Blocker
-
-This release-gate story cannot be completed in the current workspace state because the prerequisite real-model comparison chain is still missing its certified dense-Llama artifact on mounted storage.
-
-Verified blockers:
-
-- `DGR-011` is still not passed in `.scratch/distributed-gguf-runtime/prd.json`.
-- `DGR-011` is explicitly blocked in `.scratch/distributed-gguf-runtime/evidence/DGR-011/BLOCKED.md`.
-- `DGR-011` depends on `DGR-010`, and `DGR-010` is blocked because there is no certified dense-Llama artifact available on the mounted drive.
-- Current mounted-model storage still only shows Qwen artifacts and llama.cpp vocab GGUFs, not the certified dense-Llama GGUF/safetensors pair needed for a comparable real run.
-
-## Verified current state
-
-- The DGR-001 performance contract exists and defines the benchmark lanes, metrics, and stop condition that later release gates must keep unchanged.
-- The DGR-012 scheduler and DGR-013 failure semantics evidence are present and usable as supporting context, but they do not satisfy the real final comparison required here.
-- `packages/node/meshnet_node/performance_contract.py` already contains the contract metadata and a live endpoint benchmark shim, but there is no recorded DGR-014 release-gate run and no final immutable comparison artifact.
-- `evidence/DGR-014/README.md` does not exist yet because the acceptance criteria could not be completed.
-
-## Commands run
-
-```bash
-sed -n '1,260p' .claude/memory/MEMORY.md
-sed -n '1,260p' .scratch/distributed-gguf-runtime/RALPH-CONTEXT.md
-sed -n '1,260p' .scratch/distributed-gguf-runtime/issues/14-enforce-the-gguf-versus-safetensors-release-gate.md
-sed -n '1,260p' .ralph-tui/progress.md
-git status --short
-sed -n '1,260p' .scratch/distributed-gguf-runtime/prd.json
-sed -n '1,260p' .scratch/distributed-gguf-runtime/evidence/DGR-001/README.md
-sed -n '1,260p' .scratch/distributed-gguf-runtime/evidence/DGR-012/README.md
-sed -n '1,260p' .scratch/distributed-gguf-runtime/evidence/DGR-013/README.md
-sed -n '1,260p' .scratch/distributed-gguf-runtime/evidence/DGR-011/BLOCKED.md
-sed -n '1,260p' .scratch/distributed-gguf-runtime/evidence/DGR-010/BLOCKED.md
-find /run/media/popov/d/DEV/models /run/media/popov/d/DEV/llamacpp/llama.cpp/models -maxdepth 4 \( -iname '*llama*' -o -iname '*deepseek*' -o -iname '*dense*' -o -name '*.gguf' -o -name '*.safetensors' -o -name 'config.json' \)
-```
-
-## Known limitations
-
-- No certified dense-Llama artifact is mounted, so the real distributed safetensors-versus-GGUF comparison cannot be executed.
-- No immutable release-gate evidence can be produced without that artifact and the completed DGR-011 route comparison.
-- No code was changed in this iteration.
-
-## Compatibility notes
-
-- The DGR-001 contract remains the source of truth for thresholds and metric names.
-- Any future DGR-014 run must keep those thresholds unchanged and compare the same certified model/hardware/network scenario for both routes.
-
-## Dependent-story handoff
-
-- Finish `DGR-010` and `DGR-011` first with a certified dense-Llama artifact on mounted storage.
-- Then run the current distributed safetensors and distributed GGUF routes on the same comparable scenario, record the final numbers in `evidence/DGR-014/README.md`, and update the issue status only after the gate passes.

.scratch/distributed-gguf-runtime/evidence/DGR-015/BLOCKED.md

@@ -1,78 +0,0 @@
-# DGR-015 — Blocked handoff
-
-Status: blocked
-Date: 2026-07-16
-
-## Blocker
-
-This story cannot be completed in the current workspace state because its
-mandatory prerequisite, DGR-014, is still not passed.
-
-Verified blocker chain:
-
-- `.scratch/distributed-gguf-runtime/prd.json` still marks `DGR-014` as
-  `"passes": false`, so DGR-015 is not released for completion.
-- `.scratch/distributed-gguf-runtime/evidence/DGR-014/BLOCKED.md` records the
-  release-gate blocker: the certified dense-Llama artifact required for the
-  comparable real-model comparison is not mounted on this machine.
-- `DGR-014` depends on `DGR-011`, which is also blocked because `DGR-010`
-  cannot run without that same certified dense-Llama artifact.
-- The current codebase still fails closed for `qwen3` / `qwen3-moe` in
-  `packages/node/meshnet_node/boundary_adapter.py`, which is correct for the
-  current state but means no Qwen3 family recipe is certified yet.
-
-## Verified current state
-
-- Dense-Llama boundary semantics, Hot KV isolation, batching, and failure
-  semantics are already implemented and covered by prior stories.
-- Qwen3 strings are present in tracker/model metadata, but they are not yet
-  backed by a certified architecture adapter or real-model acceptance evidence.
-- No `evidence/DGR-015/README.md` exists yet because the acceptance criteria
-  could not be completed.
-
-## Commands run
-
-```bash
-sed -n '1,260p' .claude/memory/MEMORY.md
-sed -n '1,260p' .scratch/distributed-gguf-runtime/RALPH-CONTEXT.md
-sed -n '1,260p' .scratch/distributed-gguf-runtime/issues/15-add-and-certify-a-qwen3-qwen3-moe-adapter.md
-sed -n '1,260p' .scratch/distributed-gguf-runtime/architecture.md
-sed -n '1,260p' CONTEXT.md
-sed -n '1,260p' .scratch/distributed-gguf-runtime/prd.json
-sed -n '1,260p' .scratch/distributed-gguf-runtime/evidence/DGR-014/BLOCKED.md
-sed -n '1,260p' .scratch/distributed-gguf-runtime/evidence/DGR-013/README.md
-sed -n '1,260p' .scratch/distributed-gguf-runtime/evidence/DGR-012/README.md
-sed -n '1,260p' packages/node/meshnet_node/boundary_adapter.py
-sed -n '1,260p' packages/node/meshnet_node/model_catalog.py
-sed -n '1,220p' packages/node/meshnet_node/model_metadata.json
-sed -n '1,260p' packages/tracker/meshnet_tracker/capability.py
-sed -n '1,260p' packages/tracker/meshnet_tracker/server.py
-rg -n "qwen3|qwen3-moe|Qwen3|MoE|router|top-k|shared expert|shared_expert|expert" packages/node/meshnet_node packages/tracker/meshnet_tracker tests -g '!**/__pycache__/**'
-git status --short
-```
-
-## Known limitations
-
-- No certified dense-Llama artifact is mounted, so DGR-014 cannot complete and
-  DGR-015 remains blocked behind it.
-- No real consumer-hardware Qwen3 acceptance run was possible in this workspace.
-- No code was changed in this iteration.
-
-## Compatibility notes
-
-- The current boundary adapter intentionally fails closed for uncertified
-  architectures. That is the correct behavior until a dedicated Qwen3 adapter is
-  implemented and certified.
-- Existing dense-Llama coverage and Hot KV semantics remain the source of truth
-  for the shared protocol and cache behavior.
-
-## Dependent-story handoff
-
-- Finish `DGR-010`, `DGR-011`, and `DGR-014` first with a certified dense-Llama
-  artifact on mounted storage.
-- Once the release gate passes, implement the Qwen3 family adapter as a separate
-  certified architecture rather than by extending dense-Llama with unchecked name
-  substitutions.
-- Record the real-model Qwen3 parity, admission, memory, and communication
-  evidence in `evidence/DGR-015/README.md`, then update the issue status only
-  after the gate passes.

.scratch/distributed-gguf-runtime/evidence/DGR-016/README.md

@@ -1,145 +0,0 @@
-# DGR-016 — Upstream llama.cpp collaboration package
-
-Status: partial, blocked by DGR-010
-Date: 2026-07-16
-
-## Summary
-
-Assembled the upstream-facing collaboration package for llama.cpp without
-pulling Meshnet routing or control-plane logic into the upstream ask.
-
-Durable outputs created for this story:
-
-- `api-note.md` with the generic hook split and patch-per-concern proposal
-- `outreach.md` with a maintainer-facing draft for Georgi/llama.cpp
-
-The package is grounded in the existing research artifacts and the already
-implemented deterministic tests for:
-
-- range-aware GGUF ownership and introspection
-- architecture boundary input/output
-- layer-filtered KV/session ownership
-- reproducible pinned worker build wiring
-
-The story itself remains blocked because DGR-010 is still marked `passes: false`
-and only has a blocked handoff, not a completed real-model acceptance README.
-
-## Files changed
-
-- `.scratch/distributed-gguf-runtime/evidence/DGR-016/README.md`
-- `.scratch/distributed-gguf-runtime/evidence/DGR-016/api-note.md`
-- `.scratch/distributed-gguf-runtime/evidence/DGR-016/outreach.md`
-
-## Commands run and real results
-
-### Dependency and context review
-
-```bash
-sed -n '1,260p' .scratch/distributed-gguf-runtime/RALPH-CONTEXT.md
-sed -n '1,260p' .scratch/distributed-gguf-runtime/issues/16-produce-the-upstream-llama-cpp-collaboration-package.md
-sed -n '1,260p' .scratch/distributed-gguf-runtime/evidence/DGR-010/BLOCKED.md
-sed -n '1,260p' docs/adr/0024-distributed-gguf-runtime.md
-sed -n '1,260p' .scratch/distributed-gguf-runtime/architecture.md
-sed -n '1,260p' .scratch/distributed-gguf-runtime/decision-framework.md
-sed -n '1,260p' .scratch/distributed-gguf-runtime/implementation-strategy.md
-sed -n '1,260p' CONTEXT.md
-```
-
-Result:
-
-- confirmed the runtime target is a small pinned llama.cpp worker with Meshnet
-  kept outside upstream
-- confirmed DGR-010 is still blocked because there is no certified dense-Llama
-  artifact on mounted storage
-
-### Package-relevant targeted pytest
-
-```bash
-python -m pytest -q tests/test_llama_worker_build.py tests/test_gguf_backend.py tests/test_gguf_ownership.py tests/test_boundary_adapter.py tests/test_hot_kv_state.py
-```
-
-Result:
-
-- `50 passed in 0.90s`
-
-### Broader focused pytest slice
-
-```bash
-python -m pytest -q tests/test_llama_worker_build.py tests/test_native_shard_protocol.py tests/test_gguf_backend.py tests/test_boundary_adapter.py tests/test_gguf_ownership.py tests/test_hot_kv_state.py tests/test_kv_cache_distributed.py
-```
-
-Result:
-
-- `58 passed, 1 skipped, 9 failed, 12 errors in 1.27s`
-- failures were pre-existing environment issues, not this documentation-only
-  package:
-  - `tests/test_native_shard_protocol.py` imported generated protobuf code built
-    against gencode 7.35.0 while the active runtime is 6.33.6
-  - `tests/test_kv_cache_distributed.py` hit sandbox socket `PermissionError`
-    when trying to bind localhost servers
-
-### Research evidence review
-
-```bash
-sed -n '1,260p' docs/research/distributed-gguf-landscape.md
-sed -n '1,260p' docs/research/distributed-gguf-github-followup.md
-sed -n '1,220p' .scratch/distributed-gguf-runtime/evidence/DGR-004/README.md
-sed -n '1,260p' .scratch/distributed-gguf-runtime/evidence/DGR-006/README.md
-sed -n '1,260p' .scratch/distributed-gguf-runtime/evidence/DGR-007/README.md
-sed -n '1,260p' .scratch/distributed-gguf-runtime/evidence/DGR-009/README.md
-```
-
-Result:
-
-- confirmed Nakshatra and prima.cpp are the right source/test donors for the
-  upstream ask
-- confirmed the generic API surface is range loading, boundary I/O, and KV
-  ownership, not Meshnet policy
-
-### Package assembly
-
-No code generation, downloads, or model execution were required for this story.
-The package is documentation-only and deterministic.
-
-```bash
-python -m compileall -q packages tests
-git diff --check
-```
-
-Result:
-
-- both commands exited 0
-
-## Correctness / performance / hardware classification
-
-- Correctness evidence: research-only, no live model execution
-- Performance evidence: none in this story
-- Hardware evidence: none in this story
-
-## Known limitations and deferred work
-
-- DGR-010 remains blocked, so this package cannot be treated as the final
-  release-ready upstream handoff.
-- The outreach draft is human-ready but not sent.
-- The doc package does not change llama.cpp source code; it only prepares the
-  upstream ask and test mapping.
-
-## Compatibility / migration notes
-
-- Exact upstream pin for the eventual patch series: `b3c9d1b846cc80a6360adb6aeaa4fcd8c4c8dcac`
-- The proposed patch split is:
-  1. range-aware loading and ownership introspection
-  2. boundary input/output and named tensor bundles
-  3. layer-filtered KV and local sequence ownership
-- Meshnet routing, billing, relay transport, and volunteer-network policy stay
-  outside llama.cpp.
-- The deterministic examples already exist in the tree and can be trimmed into
-  upstream-facing MREs when the human maintainer sends the package.
-
-## Dependent-story handoff
-
-- DGR-010 must clear before any real-model validation can be cited as the final
-  end-to-end proof for this upstream package.
-- Once DGR-010 has a completed evidence README, the package can be refreshed
-  with the real-model context and sent to the llama.cpp maintainers as a
-  smaller review bundle.

.scratch/distributed-gguf-runtime/evidence/DGR-016/api-note.md

@@ -1,90 +0,0 @@
-# DGR-016 API note: narrow llama.cpp hooks, no Meshnet policy
-
-This note is the upstream-facing shape for the collaboration package.
-
-## Goal
-
-Keep the llama.cpp ask small:
-
-- expose generic model-layer hooks that are useful to any local or remote
-  layer-worker setup;
-- keep Meshnet routing, session ownership, billing, and relay transport out of
-  llama.cpp;
-- preserve one patch per concern so the series rebases cleanly on the pinned
-  upstream commit.
-
-## Concern 1: range-aware loading and authoritative tensor ownership
-
-Requested surface:
-
-- accept a contiguous `[start_layer, end_layer)` range;
-- expose whether the worker owns embeddings, final norm, and final head;
-- make the loaded range authoritative from the model state, not from CLI
-  claims;
-- allow unowned tensors to be absent rather than fabricated.
-
-Why this is upstreamable:
-
-- it is generic loader and introspection plumbing;
-- it helps any local partitioned inference mode;
-- it does not require any Meshnet identity, route, or transport type.
-
-Minimal examples/tests:
-
-- `tests/test_gguf_ownership.py`
-- `tests/test_llama_worker_build.py`
-
-## Concern 2: architecture boundary input/output
-
-Requested surface:
-
-- accept a versioned boundary bundle carrying one or more named tensors;
-- support an unnormalized residual stream as the intermediate handoff;
-- keep final norm, LM head, and sampling on the tail shard only;
-- keep the bundle format explicit about name, shape, dtype, byte order, and
-  fragments.
-
-Why this is upstreamable:
-
-- it matches both dense Llama and other certified adapter families;
-- it does not assume Meshnet or any specific wire protocol;
-- it gives a stable ABI for a layer-worker boundary.
-
-Minimal examples/tests:
-
-- `tests/test_boundary_adapter.py`
-- `tests/test_native_shard_protocol.py`
-
-## Concern 3: layer-filtered KV and session mapping
-
-Requested surface:
-
-- let the worker own KV only for its layer range;
-- map a stable session/context identifier to the local sequence;
-- allow cache miss, stale epoch, truncate, release, and eviction semantics;
-- reject incompatible cache recipes rather than trying to heal them silently.
-
-Why this is upstreamable:
-
-- it is a local sequence/KV API, not a network scheduler;
-- it is useful to any supervisor that needs one process per layer range;
-- it keeps session semantics outside llama.cpp while still making the worker
-  stateful in a controlled way.
-
-Minimal examples/tests:
-
-- `tests/test_hot_kv_state.py`
-- `tests/test_kv_cache_distributed.py`
-
-## Suggested patch split
-
-Keep the series narrow and independently reviewable against the exact pinned
-commit `b3c9d1b846cc80a6360adb6aeaa4fcd8c4c8dcac`:
-
-1. `range-aware-loading` and ownership introspection.
-2. `boundary-input-output` and named tensor bundle handoff.
-3. `layer-filtered-kv` and sequence ownership.
-
-The current Meshnet worker scaffold remains a project-owned wrapper and is not
-part of the upstream ask.
-

.scratch/distributed-gguf-runtime/evidence/DGR-016/outreach.md

@@ -1,43 +0,0 @@
-# DGR-016 outreach draft
-
-Subject: Narrow llama.cpp hooks for range loading, boundary I/O, and local KV ownership
-
-Hi Georgi and llama.cpp maintainers,
-
-We have been building a distributed GGUF route on top of a Meshnet control
-plane, and the narrow upstreamable seam is now clear enough to summarize.
-
-We are not asking llama.cpp to own Meshnet routing, billing, relay transport,
-or any volunteer-network policy. The upstream ask is limited to generic local
-hooks that make partitioned inference easier to implement and easier to review:
-
-1. Range-aware loading and ownership introspection for contiguous layer ranges.
-2. Architecture-defined boundary input/output using an explicit named-tensor
-   bundle.
-3. Layer-filtered KV ownership and stable local sequence mapping.
-
-Why we think this is generally useful:
-
-- Nakshatra already demonstrates the value of a narrow layer-worker seam and
-  partial GGUF loading.
-- prima.cpp shows the same idea from a different angle with selective loading,
-  local KV, and boundary residual transport.
-- Both projects suggest the same conclusion: the missing API is not Meshnet
-  specific, it is a local runtime seam that any layer-partitioned supervisor can
-  use.
-
-The package we would upstream is intentionally split into one concern per patch
-so review stays small:
-
-- range-aware loading and tensor ownership;
-- boundary I/O for intermediate residual state;
-- layer-filtered KV and sequence ownership.
-
-If useful, we can send the concrete MRE/test mapping next. We already have
-deterministic examples covering the loader, boundary contract, and KV/session
-semantics in the Meshnet tree, and we can trim them into upstream-focused test
-cases.
-
-Thanks,
-Meshnet maintainers
-

.scratch/distributed-gguf-runtime/evidence/DGR-017/README.md

@@ -0,0 +1,114 @@
+# DGR-017 evidence — superseded backlog cleanup
+
+**Completed:** 2026-07-16
+**Branch:** `ralph/distributed-gguf-runtime`
+**Planning checkpoint before cleanup:** `81b1fa6`
+**Authority:** `.scratch/distributed-gguf-runtime/prd.json`
+
+## Outcome
+
+The old DGR-001…016 completion claims and active artifacts were reconciled against the live branch. No old pass state transferred to the new implementation roadmap.
+
+The active `packages/` and `tests/` trees were restored exactly to `origin/master`. The branch therefore no longer exposes a nominal GGUF startup path backed by unimplemented transport methods, a protobuf-only native scaffold, or isolated synthetic scheduler/cache/failure modules as if they were a working distributed GGUF runtime.
+
+## Classification and disposition
+
+### Retained
+
+- Accepted ADRs and repository research, including `docs/research/colibri-implementation-audit.md`.
+- The authoritative 55-story roadmap `DGR-017…071` and its generated issue specifications.
+- The real public-relay smoke benchmark, moved with provenance to `legacy-public-relay-smoke-benchmark.json`.
+- Git history containing the complete superseded implementation/reference work.
+
+### Removed from the active tree
+
+- Legacy issue specifications DGR-001…016 and their stale/blocked/synthetic evidence directories.
+- The nonfunctional `gguf_backend` startup path whose gRPC execution methods raised not-implemented errors.
+- Synthetic/reference-only boundary, Hot KV, scheduler, failure, recipe, ownership, and native-protocol modules that were not a real llama.cpp Shard runtime.
+- The protobuf round-trip-only native scaffold, placeholder llama.cpp patch, generated bindings/build workspace, and associated tests.
+- Tracker/admission/source modifications coupled to that superseded scaffold.
+
+### Confirmed absent and still required
+
+- Real standalone C++ gRPC Shard worker.
+- Exact pinned llama.cpp manifest and verified patch stack.
+- Range-aware GGUF tensor ownership and real ranged execution.
+- Real Shard-local llama.cpp KV/V4 auxiliary state.
+- DeepSeek V4 boundary adapter and ranged parity.
+- Real multi-machine DeepSeek V4 alpha or beta acceptance.
+
+These remain `passes: false` in DGR-018…071.
+
+## Before-cleanup baseline
+
+Command:
+
+```bash
+.venv-rocm/bin/python -m pytest -q \
+  tests/test_performance_contract.py tests/test_native_shard_protocol.py \
+  tests/test_gguf_ownership.py tests/test_boundary_adapter.py \
+  tests/test_hot_kv_state.py tests/test_gguf_backend.py \
+  tests/test_batch_scheduler.py tests/test_failure_semantics.py \
+  tests/test_llama_worker_build.py tests/test_node_admission.py \
+  tests/test_node_capability.py tests/test_tracker_capability_admission.py
+```
+
+Result:
+
+```text
+216 passed, 2 skipped, 1 failed, 1 warning
+```
+
+The failure was a synthetic capability-test helper `KeyError: 'compatibility_fingerprint'`. The warning was a pre-existing heartbeat-thread `SystemExit` warning.
+
+## Cleanup verification
+
+### Source equality
+
+Command:
+
+```bash
+git diff --quiet origin/master -- packages tests
+```
+
+Result:
+
+```text
+packages_tests_match_origin_master=yes
+```
+
+The staged cleanup removes approximately 15.3k obsolete source/test/evidence lines from the active branch.
+
+### Cleanup-relevant regression suite
+
+Command:
+
+```bash
+.venv-rocm/bin/python -m pytest -q \
+  tests/test_node_admission.py tests/test_node_capability.py \
+  tests/test_tracker_capability_admission.py \
+  tests/test_kv_cache_distributed.py tests/test_real_distributed_inference.py
+```
+
+Result:
+
+```text
+119 passed, 2 skipped, 1 warning in 15.90s
+```
+
+The warning is the same pre-existing heartbeat-thread `SystemExit` warning.
+
+### Known `origin/master` limitations
+
+The wider routing run produced `210 passed, 2 skipped, 4 failed, 1 warning`. Each failure reproduced individually while `packages/` and `tests/` matched `origin/master` exactly:
+
+- `test_tracker_models_endpoint_lists_registered_hf_repo_and_short_name_alias`
+- `test_torch_node_applies_tracker_load_shard_directive`
+- `test_shard_heal_cycle_surviving_node_covers_dead_peers_gap`
+- `test_a_node_with_an_unusable_precision_covers_no_layers`
+
+They are recorded as pre-existing baseline defects and were not repaired or hidden by this cleanup story.
+
+## Dependency handoff
+
+DGR-018 and later stories must start from the cleaned upstream-equivalent runtime tree. Reuse concepts from superseded commits only by explicitly porting the smallest verified slice under the new story’s contracts, tests, and evidence gates. Git history is provenance, not completion evidence.

.scratch/distributed-gguf-runtime/evidence/DGR-018/README.md

@@ -0,0 +1,204 @@
+# DGR-018 evidence — canonical Ralph and Gitea metadata schema
+
+**Completed:** 2026-07-16
+**Branch:** `ralph/distributed-gguf-runtime`
+**Authority:** `.scratch/distributed-gguf-runtime/prd.json`
+**Dependency:** DGR-017 (`evidence/DGR-017/README.md`) — cleaned backlog reconciled to `origin/master`; no old pass state transferred.
+
+## Objective
+
+Make `prd.json` the validated source from which Markdown (and, later, Gitea) issues
+can be generated losslessly, per
+`.scratch/distributed-gguf-runtime/issues/018-define-canonical-ralph-and-gitea-metadata-schema.md`.
+
+## Pre-existing state found (not caused by this story)
+
+Before any change in this session, `git status` showed `.scratch/distributed-gguf-runtime/prd.json`
+already modified in the working tree relative to `HEAD` (commit `369b207`), with no corresponding
+progress-log entry. Diffing against `HEAD` showed the working copy had **dropped** prd.json's
+top-level `sourceOfTruth`, `qualityGates`, `metadataSchema`, `milestones`, and `supersededStories`
+objects, while `userStories` itself was byte-identical to `HEAD`. This looked like an abandoned,
+uncommitted partial edit from a prior session, not intentional current work — those fields are
+exactly the schema/quality-gate/audit-provenance content this story depends on, and their loss
+wasn't explained by any acceptance criterion. They were restored (see "Changes" below) rather than
+silently accepted or discarded, per the instruction to investigate unexplained working-tree state
+before building on top of it.
+
+## Changes
+
+### `scripts/ralph_prd_schema.py` (new)
+
+Single module providing:
+
+- **Parse:** `load_prd(path)` — JSON load with clear `PrdValidationError`s for missing file /
+  invalid JSON / non-object document.
+- **Canonical schema registry:** `STORY_FIELDS` (name → required/type), `EXECUTION_MODES`,
+  `EVIDENCE_CLASSES`, `HARDWARE_FLAGS`, `UPSTREAM_FLAGS`, `TRIAGE_VALUES`. Covers every field named
+  in the acceptance criteria: stable `id`/`title`, `labels`, `milestone`, derived `type`
+  (`derive_type`), `dependsOn`, derived `blocks`, `triage`, `evidenceClass`, and
+  `hardware`/`model`/`upstream` flags.
+- **Structural validation:** `validate_schema(data)` — required fields, types, enum membership,
+  ID convention, `type:`/`priority:` label cardinality, non-empty `acceptanceCriteria`.
+- **Semantic validation:** `validate_semantics(data)` — unique IDs, unique titles, `dependsOn`
+  resolves to known stories (no self-dependency), dependency graph is acyclic (with a reported
+  cycle path on failure), `blocks` matches the dependency graph exactly (sorted set equality, not
+  superset), and `evidencePath` matches the per-story convention.
+- **Fresh vs. in-progress backlog:** `validate_fresh_backlog(data)` additionally requires every
+  story to start `passes: false` (for a backlog that hasn't started execution yet);
+  `validate_backlog(data)` is the composed check for a real, in-flight backlog where some stories
+  have legitimately completed.
+- **Self-consistency check:** `validate_metadata_schema_consistency(data)` — when prd.json declares
+  its own `metadataSchema`/`qualityGates` (as this one now does), verifies that self-documentation
+  hasn't drifted from what the validator actually enforces (enum sets, required/optional field
+  lists, presence of `qualityGates` and `generatedArtifactDisclaimer`). This is a no-op for minimal
+  fixture PRDs that don't carry that documentation.
+- **Generation (one-directional, prd.json → artifact):** `render_issue_markdown(story, data)`
+  renders the exact Markdown convention already used by
+  `.scratch/distributed-gguf-runtime/issues/*.md`, sourcing the "Shared quality gates" bullets from
+  `data["qualityGates"]` and the leading disclaimer from
+  `data["metadataSchema"]["generatedArtifactDisclaimer"]` (falling back to a module default only
+  when `data` omits them) — not from a duplicated Python string literal.
+  `to_gitea_issue_payload(story, data)` wraps the same body into a Gitea create-issue-shaped payload
+  (`title`, `body`, `labels`, `milestone`).
+- **Authority guard:** `check_generated_markdown_authority(text, disclaimer=...)` rejects generated
+  Markdown that's missing the disclaimer or that contains a conflicting authority claim (e.g. "this
+  file is authoritative"). There is deliberately no Markdown → prd.json parser, so a generated
+  artifact structurally cannot feed `passes` (or anything else) back into the authoritative source.
+- CLI: `python scripts/ralph_prd_schema.py validate <prd.json> [--fresh]` and
+  `... render <prd.json> <STORY-ID>`.
+
+### `.scratch/distributed-gguf-runtime/prd.json`
+
+- Restored the top-level `sourceOfTruth`, `qualityGates`, `milestones`, and `supersededStories`
+  objects to their `HEAD` content (see "Pre-existing state" above); `userStories` was already
+  identical to `HEAD` and is unchanged in content.
+- Extended `metadataSchema` (previously incomplete for this story's own acceptance criteria) with:
+  `requiredStoryFields` now also lists `notes` and `blocks` (present on all 55 stories); new
+  `optionalStoryFields: ["completionNotes"]`; new `hardwareValues`/`upstreamValues` enums (`model`
+  is documented as an open convention, not a closed enum, since quantization/model targets are
+  dynamic recipe inputs per `RALPH-CONTEXT.md`); new `typeDerivation` and `labelConventions`
+  (reserved prefixes, cardinality); new `generatedArtifactDisclaimer` (the exact string generated
+  artifacts must start with); extended `dependencyRules`/`authorityRule` prose to match what the
+  validator enforces.
+- Reworded `sourceOfTruth`'s stale "All stories are unimplemented ... passes=false" clause, which
+  was no longer accurate once DGR-017 completed.
+- Marked `DGR-018.passes = true` with `completionNotes` recording this story's outcome.
+
+### `.scratch/distributed-gguf-runtime/issues/018-define-canonical-ralph-and-gitea-metadata-schema.md`
+
+Regenerated via `render_issue_markdown` to reflect `passes: true` (checked acceptance criteria,
+"completed" status line, "Verified evidence" handoff line) — matching the same convention DGR-017's
+issue file already used for a completed story.
+
+### `tests/test_ralph_prd_schema.py` (new)
+
+108 deterministic, model-download-free, GPU-free tests:
+
+- **Parse** (4 tests): real backlog parses to 55 stories; missing file, invalid JSON, and
+  non-object documents raise `PrdValidationError`.
+- **Structural/semantic validation against the real backlog** (7 tests): passes `validate_schema`,
+  `validate_semantics`, and the composed `validate_backlog`; unique IDs/titles; all `dependsOn`
+  resolve; `blocks` matches the derived dependency graph for all 55 stories; no cycle; every
+  `passes: true` story carries `completionNotes` and an existing evidence README (a durable
+  invariant, not a hardcoded list of which stories have completed — that list will keep growing).
+- **Structural/semantic failure-mode fixtures** (13 tests): missing required field, bad enum, wrong
+  type, empty `acceptanceCriteria`, multiple `type:` labels, duplicate ID, duplicate title, unknown
+  dependency, self-dependency, dependency cycle, mismatched `blocks`, bad `evidencePath`.
+- **Fresh-backlog invariant** (3 tests): accepts all-`false`, rejects a premature `passes: true`,
+  and confirms `validate_backlog` (the in-progress variant) permits completed stories.
+- **prd.json-as-source-of-truth for boilerplate** (9 tests): `qualityGates`/`metadataSchema`
+  self-consistency checks (no-op without them, catches a drifted enum, catches a missing
+  `qualityGates`), `quality_gate_bullets` flattening order, `authority_disclaimer` precedence and
+  fallback, and 3 tests asserting the real backlog's declared schema matches the code, its 7
+  quality-gate bullets are intact, and its disclaimer matches the module default.
+- **`derive_type`** (4 tests): label-derived type, release-gate synthetic type for HITL gate
+  stories, `None` when absent, and confirmation that the real backlog's two release-gate stories
+  (`DGR-054`, `DGR-070`) derive `release-gate`.
+- **Markdown generation round trips** (55 parametrized + 6 tests): `render_issue_markdown` for
+  every story `DGR-017`..`DGR-071` is byte-for-byte identical to the corresponding file already in
+  `.scratch/distributed-gguf-runtime/issues/`; determinism; leading disclaimer; `Blocks (derived)`
+  rendering (`None` vs. listed); checkbox reflects `passes`; filename convention.
+- **Authority-claim rejection** (4 tests): accepts real generated text, rejects a missing
+  disclaimer, rejects an overriding claim, and confirms every committed issue file in
+  `.scratch/distributed-gguf-runtime/issues/` passes the check.
+- **Gitea payload generation** (3 tests): payload shape, body carries no information beyond what's
+  in prd.json, and every real story's payload is well-formed and authority-clean.
+
+## Commands and results
+
+```bash
+python3 -m pytest -q tests/test_ralph_prd_schema.py
+```
+```text
+108 passed in 0.16s
+```
+
+```bash
+python3 -m compileall -q packages tests
+```
+Exit code 0, no output (all files compile).
+
+```bash
+git diff --check
+```
+Exit code 0 (no whitespace errors).
+
+```bash
+python3 scripts/ralph_prd_schema.py validate .scratch/distributed-gguf-runtime/prd.json
+```
+```text
+OK: 55 stories validated.
+```
+
+```bash
+python3 scripts/ralph_prd_schema.py validate .scratch/distributed-gguf-runtime/prd.json --fresh
+```
+```text
+ERROR: DGR-017: fresh backlog requires passes=false, got True
+ERROR: DGR-018: fresh backlog requires passes=false, got True
+2 validation error(s).
+```
+Expected: `--fresh` is the invariant for a backlog that hasn't started execution; this backlog has
+legitimately completed two stories, so it correctly fails that stricter check while passing the
+plain (in-progress) `validate` command above.
+
+### Baseline: full repository suite (ad hoc `python3`, not a project venv)
+
+```bash
+python3 -m pytest -q
+```
+```text
+20 failed, 776 passed, 13 skipped, 2 warnings in 244.17s (0:04:04)
+```
+None of the failures touch `scripts/ralph_prd_schema.py` or `tests/test_ralph_prd_schema.py`
+(neither file existed before this story; this story adds no changes to `packages/`). Four of the
+20 failures reproduce exactly the pre-existing baseline defects DGR-017's evidence already recorded
+(`test_tracker_models_endpoint_lists_registered_hf_repo_and_short_name_alias`,
+`test_torch_node_applies_tracker_load_shard_directive`,
+`test_shard_heal_cycle_surviving_node_covers_dead_peers_gap`,
+`test_a_node_with_an_unusable_precision_covers_no_layers`). The remaining 16 (activation
+compression, dynamic routing, gossip/relay, manual route benchmark, openai gateway, TOPLoC
+calibration dispatch, tracker control plane) include a `ModuleNotFoundError: langchain` failure,
+indicating this ad hoc `python3` lacks the project's `dev` extras (`langchain-openai`, etc.) rather
+than a real regression; this environment has no project virtualenv (e.g. no `.venv-rocm`) to run
+against instead. Not investigated further as out of scope for this story.
+
+## Limitations
+
+- No real Gitea instance or API integration exists; `to_gitea_issue_payload` defines the payload
+  shape (title/body/labels/milestone) only. Creating issues against a live Gitea server is future
+  work, not claimed here.
+- `model` is intentionally validated as an open string, not a closed enum, per
+  `RALPH-CONTEXT.md`'s "Quantization and placement are dynamic recipe inputs" constraint; the schema
+  documents (`metadataSchema.modelConvention`) but does not restrict its value set.
+- Validation and generation were exercised only against this feature's `prd.json`
+  (`.scratch/distributed-gguf-runtime/prd.json`); `docs/prd.json` and other `.scratch/*/prd.json`
+  files in this repo use a materially different (simpler) shape and are out of scope.
+
+## Dependency handoff
+
+DGR-021 and DGR-025 (this story's derived `blocks`) may treat `prd.json`'s `metadataSchema`,
+`qualityGates`, and this validator/generator as stable. Any future field addition to a story shape
+must extend `STORY_FIELDS` in `scripts/ralph_prd_schema.py` and the corresponding
+`metadataSchema.requiredStoryFields`/`optionalStoryFields` in `prd.json` together —
+`validate_metadata_schema_consistency` fails closed if they drift apart.

.scratch/distributed-gguf-runtime/evidence/DGR-021/README.md

@@ -0,0 +1,101 @@
+# DGR-021 evidence — versioned named-tensor activation envelope
+
+**Completed:** 2026-07-17
+**Branch:** `distributed-gguf-runtime`
+**Authority:** `.scratch/distributed-gguf-runtime/prd.json`
+**Dependency:** DGR-018 (`evidence/DGR-018/README.md`) — canonical backlog schema / issue projection contract
+
+## Objective
+
+Establish the backend-neutral activation envelope used by direct and relayed Shard traffic, with stable versioning, named tensors, bounded fragmentation, checksum validation, and reserved extensibility for future state.
+
+## Changes
+
+### `packages/node/meshnet_node/protocol.py` (new)
+
+Added a self-contained activation-envelope module with:
+
+- `SCHEMA_NAME = "meshnet.activation-stream"` and `SCHEMA_VERSION = 1`
+- `TensorFragment`
+  - bounded byte fragments with offset, compression tag, checksum, and extension preservation
+  - deterministic `to_dict()` / `from_dict()` round-trip
+- `NamedTensor`
+  - named tensor metadata: `name`, `shape`, `dtype`, `byte_order`, `compression`, `checksum`, `fragments`
+  - fragmentation via `from_bytes(..., max_fragment_bytes=...)`
+  - checksum validation over reconstructed tensor bytes
+  - unknown-field preservation via `extensions`
+- `ActivationEnvelope`
+  - top-level fields for `request_id`, `work_id`, `route_session`, `route_epoch`, `shard_start`, `effective_start`, `phase`, `position`, and `idempotency_step`
+  - reserved extension fields for `token_id_sideband`, `architecture_state`, `recurrent_state`, and `mtp`
+  - deterministic canonical serialization (`to_bytes`) and round-trip parsing (`from_bytes`)
+  - size-limit enforcement (`to_bytes(max_bytes=...)`)
+  - conversion from a live `TensorPayload` into the envelope and back again
+
+### `packages/node/meshnet_node/model_backend.py`
+
+Extended `TensorPayload` with envelope conversion helpers:
+
+- `TensorPayload.to_envelope(...)`
+- `TensorPayload.from_envelope(...)`
+
+These keep the existing activation payload interface intact while exposing the new versioned envelope as the shared protocol layer.
+
+### `tests/test_activation_envelope.py` (new)
+
+Added focused deterministic tests covering:
+
+- deterministic envelope serialization and round-trip parsing
+- tensor fragmentation and checksum validation
+- unknown-field preservation at both envelope and tensor levels
+- size-limit rejection
+- `TensorPayload` ↔ envelope round-trip
+
+### `.scratch/distributed-gguf-runtime/prd.json`
+
+Marked `DGR-021.passes = true` and added completion notes recording the envelope implementation and verification commands.
+
+## Commands and results
+
+```bash
+pytest -q tests/test_activation_envelope.py
+```
+
+```text
+5 passed in 0.06s
+```
+
+```bash
+pytest -q tests/test_activation_envelope.py tests/test_kv_cache_distributed.py -k 'session_is_stable_and_decode_payloads_are_single_token or large_prefill_activation_survives_zstd_compressed_hop'
+```
+
+```text
+..                                                                       [100%]
+2 passed, 21 deselected in 1.84s
+```
+
+```bash
+python3 -m compileall packages/node/meshnet_node tests/test_activation_envelope.py
+```
+
+```text
+Listing 'packages/node/meshnet_node'...
+Listing 'packages/node/meshnet_node/native_protocol'...
+Compiling 'tests/test_activation_envelope.py'...
+```
+
+```bash
+git diff --check
+```
+
+```text
+No whitespace errors
+```
+
+## Limitations
+
+- The envelope is implemented as a canonical deterministic JSON contract with dataclasses and conversion hooks, not generated `.proto` classes. The environment had `protobuf` available but not the `grpc_tools` generation toolchain, so I did not materialize a compiled proto artifact here.
+- The direct/relayed HTTP/WebSocket transports remain byte-oriented; the envelope is the shared structured contract layered above those transports.
+
+## Dependency handoff
+
+DGR-022 and later shard-control stories can reuse the envelope contract and its `TensorPayload` conversion hooks as the stable activation metadata layer. Future work that requires generated protobuf code can replace the JSON serialization with a generated wire codec without changing the top-level field contract defined here.

.scratch/distributed-gguf-runtime/evidence/DGR-022/README.md

@@ -0,0 +1,46 @@
+# DGR-022 evidence — Shard lifecycle and structured status RPC contract
+
+**Completed:** 2026-07-17
+**Branch:** `ralph/distributed-gguf-runtime`
+**Authority:** `.scratch/distributed-gguf-runtime/prd.json`
+
+## Outcome
+
+Implemented the versioned, backend-neutral lifecycle/status contract consumed by a future generated gRPC binding. The contract keeps Meshnet routing, identity, authentication policy, billing, and llama.cpp ownership outside the worker contract.
+
+## Implemented
+
+- `packages/node/meshnet_node/shard_lifecycle.py`
+  - capability, health, session, cancellation, release, and metrics RPC names
+  - schema version negotiation and fail-closed unsupported-version handling
+  - structured status/error taxonomy with retryability and details
+  - lifecycle state machine for prefill/decode/cancel/release transitions
+  - monotonic idempotency-step enforcement and duplicate rejection
+  - bounded frame/byte flow control with cancellation-aware waits
+  - explicit cache expectation/result types
+  - deadline policy and TLS/auth transport hooks
+  - deterministic contract serialization round-trip
+- `tests/test_shard_lifecycle.py`
+  - contract round-trip and RPC coverage
+  - unsupported-version rejection
+  - malformed transition and idempotency rejection
+  - cancellation/release behavior
+  - bounded flow-control behavior
+  - TLS hook and incomplete-contract fail-closed behavior
+
+## Verification
+
+```text
+$ PYTHONPATH=packages/node pytest -q tests/test_shard_lifecycle.py tests/test_activation_envelope.py
+17 passed in 0.10s
+```
+
+The existing DGR-021 activation-envelope tests remain green alongside DGR-022.
+
+## Scope limitation
+
+This story defines the lifecycle/status contract only. Generated Python/C++ protobuf bindings and the concrete `shard_runtime.proto` generation pipeline are DGR-023 and remain separate.
+
+## Dependency handoff
+
+DGR-023 may consume the RPC names, status taxonomy, version identity, deadlines, flow-control limits, and TLS/auth hooks when the canonical `.proto` schema and toolchain are provisioned.

.scratch/distributed-gguf-runtime/evidence/README.md

@@ -1,15 +1,15 @@
-# Ralph task evidence
+# Distributed GGUF Runtime evidence
 
-Each completed story creates `evidence/<TASK-ID>/README.md`. Fresh dependent iterations must read it before coding.
+> **Specification status:** planning artifacts only. No distributed GGUF runtime is implemented. DGR-017 cleanup is complete; no runtime implementation story has completion credit. `prd.json` is authoritative.
 
-Required README sections:
+## Authority and classes
 
-1. Summary and acceptance decision.
-2. Exact files changed.
-3. Commands run and real exit/results.
-4. Correctness, performance and hardware evidence classification.
-5. Known limitations and deferred work.
-6. Compatibility/migration notes.
-7. Explicit handoff for each dependent story.
+Evidence supports but never overrides `prd.json`. Valid classes are `model-free`, `fixture`, `real-model`, `real-hardware`, and `release`; lower classes cannot satisfy higher-class acceptance. Legacy DGR-001..016 directories remain unchanged for DGR-017 provenance audit and confer no completion credit.
 
-Store raw machine-readable metrics, manifests and protocol artifacts beside the README. Never store secrets, model weights, build outputs or Ralph iteration logs here.
+## Future story layout
+
+Each DGR-017..071 story writes `evidence/<ID>/README.md` with summary, exact changed files, exact commands and real outputs, limitations, compatibility/migration notes, and dependent-story handoff. Machine-readable contracts, manifests, metrics, and raw logs live beside it. Never fabricate output.
+
+Real runs record exact model SHA and all split hashes, tokenizer, quant/recipe, llama.cpp pin+patch identity, backend/driver/toolchain, host/hardware/network, commands/environment (without secrets), raw parity/performance/resource results, and evidence class. Models live on configured mounted-drive storage, never `/home`.
+
+Routing certification records prove only the exact exercised backend/model/recipe lane. Compile-only, fixture, failed, or unavailable lanes remain registered-dark. V4 cache/state evidence must show KV and CSA/HCA/SWA/indexer/compressor data remain shard-local/session-keyed; route recovery evidence must show cache miss plus re-prefill/restart, not migration.

.scratch/distributed-gguf-runtime/gitea-issues.json

@@ -0,0 +1,335 @@
+{
+  "repository": "https://git.d-popov.com/popov/neuron-tai",
+  "stories": {
+    "DGR-017": {
+      "number": 1,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/1",
+      "state": "closed",
+      "status": "completed"
+    },
+    "DGR-018": {
+      "number": 2,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/2",
+      "state": "closed",
+      "status": "completed"
+    },
+    "DGR-019": {
+      "number": 3,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/3",
+      "state": "open",
+      "status": "ready"
+    },
+    "DGR-020": {
+      "number": 4,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/4",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-021": {
+      "number": 5,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/5",
+      "state": "closed",
+      "status": "completed"
+    },
+    "DGR-022": {
+      "number": 6,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/6",
+      "state": "open",
+      "status": "ready"
+    },
+    "DGR-023": {
+      "number": 7,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/7",
+      "state": "open",
+      "status": "ready"
+    },
+    "DGR-024": {
+      "number": 8,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/8",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-025": {
+      "number": 9,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/9",
+      "state": "open",
+      "status": "ready"
+    },
+    "DGR-026": {
+      "number": 10,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/10",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-027": {
+      "number": 11,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/11",
+      "state": "open",
+      "status": "ready"
+    },
+    "DGR-028": {
+      "number": 12,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/12",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-029": {
+      "number": 13,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/13",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-030": {
+      "number": 14,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/14",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-031": {
+      "number": 15,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/15",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-032": {
+      "number": 16,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/16",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-033": {
+      "number": 17,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/17",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-034": {
+      "number": 18,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/18",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-035": {
+      "number": 19,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/19",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-036": {
+      "number": 20,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/20",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-037": {
+      "number": 21,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/21",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-038": {
+      "number": 22,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/22",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-039": {
+      "number": 23,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/23",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-040": {
+      "number": 24,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/24",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-041": {
+      "number": 25,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/25",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-042": {
+      "number": 26,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/26",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-043": {
+      "number": 27,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/27",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-044": {
+      "number": 28,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/28",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-045": {
+      "number": 29,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/29",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-046": {
+      "number": 30,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/30",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-047": {
+      "number": 31,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/31",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-048": {
+      "number": 32,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/32",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-049": {
+      "number": 33,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/33",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-050": {
+      "number": 34,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/34",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-051": {
+      "number": 35,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/35",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-052": {
+      "number": 36,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/36",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-053": {
+      "number": 37,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/37",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-054": {
+      "number": 38,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/38",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-055": {
+      "number": 39,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/39",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-056": {
+      "number": 40,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/40",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-057": {
+      "number": 41,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/41",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-058": {
+      "number": 42,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/42",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-059": {
+      "number": 43,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/43",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-060": {
+      "number": 44,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/44",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-061": {
+      "number": 45,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/45",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-062": {
+      "number": 46,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/46",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-063": {
+      "number": 47,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/47",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-064": {
+      "number": 48,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/48",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-065": {
+      "number": 49,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/49",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-066": {
+      "number": 50,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/50",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-067": {
+      "number": 51,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/51",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-068": {
+      "number": 52,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/52",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-069": {
+      "number": 53,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/53",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-070": {
+      "number": 54,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/54",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-071": {
+      "number": 55,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/55",
+      "state": "open",
+      "status": "blocked"
+    }
+  }
+}

.scratch/distributed-gguf-runtime/implementation-strategy.md

@@ -1,241 +1,40 @@
-# Focused implementation strategy: performant concurrent distributed inference
+# Distributed GGUF Runtime implementation strategy
 
-Status: Accepted planning direction
-Last updated: 2026-07-13
+> **Specification status:** planning artifacts only. No distributed GGUF runtime is implemented. DGR-017 cleanup is complete; no runtime implementation story has completion credit. `prd.json` is authoritative.
 
-## Product objective
+## Execution model
 
-Enable clients to run top open models that do not fit on one consumer machine by combining independently owned model Shards into performant, concurrent Inference Routes.
+Execute one numerically ordered, dependency-ready story per fresh Ralph context. Read `RALPH-CONTEXT.md`, source issue, and dependency evidence first; use TDD/fixture-first verification; finish with exact evidence. `prd.json` is the only state authority.
 
-The project is not trying to reproduce every vLLM feature or support every inference engine. It is optimizing for:
+## Sequence
 
-1. Models larger than one node's RAM/VRAM.
-2. Useful interactive decode speed on consumer CPU, AMD, NVIDIA, Vulkan, and mixed routes where certified.
-3. Multiple concurrent Route Sessions without cache corruption or global serialization.
-4. A lean runtime with one control plane and one primary GGUF engine.
-5. Measured improvement over the existing Transformers/safetensors implementation.
+1. **M0 DGR-017..020:** reconcile legacy reality, lock metadata/performance contracts, and run the independent whole-model baseline.
+2. **M1 DGR-021..033:** protocol/lifecycle/codegen, exact identities and split artifacts, pinned upstream/patches, CPU then accelerator builds, `ShardEngine`, fixtures, fake worker.
+3. **M2 DGR-034..043:** dense ranged ownership/boundary/parity/local state, worker integration, supervision/direct-relay, and measured GGUF inputs to unchanged routing.
+4. **M3 DGR-044..054:** pin/inventory V4, adapt upstream boundary/local state/MoE/hash execution, pass parity and real 2–4 scenario, then enforce alpha with MTP off.
+5. **M4 DGR-055..067:** batching/backpressure/failure/recovery/long-context, existing-routing 10+ certification, real scale, measured optimization/compression, MTP contract+implementation, hardware certification.
+6. **M5 DGR-068..071:** packages, human upstream collaboration, beta gate (including MTP), and pin/patch/certification maintenance.
 
-## Current reality
+## Guardrails
 
-The existing project already owns the differentiating distributed control plane:
 
-- Tracker-selected contiguous Shards.
-- Stable Route Sessions.
-- Local per-Shard Hot KV State in the Transformers reference backend.
-- Binary Activation Seams.
-- Relay/direct routing, cancellation, telemetry, billing, and capability admission.
-- Persistent relay and direct transport optimizations.
+## Locked scope
 
-The missing production path is a native GGUF execution worker that can load and execute only an assigned layer range while retaining local Hot KV State for concurrent Route Sessions.
+- Existing Meshnet Tracker routing, load balancing, billing, telemetry, relay, and provider semantics are backend-agnostic and are **not redesigned**. GGUF contributes exact compatibility, range/capacity, queue/load, seam-cost, health/reliability, and certification inputs only.
+- The data plane is a standalone project-owned C++ Shard worker with gRPC/Protobuf and a project-owned `ShardEngine` boundary.
+- llama.cpp is fetched at one exact commit into an ignored workspace from an in-repo manifest, then a numbered minimal patch stack is applied. There is no submodule, vendored tree, or permanent-fork dependency.
+- llama.cpp owns DeepSeek V4 graphs, mHC, MoE, attention, hash routing, and kernels. Meshnet adds only range-ownership hooks, typed boundary/local-state adapters, worker integration, and parity/certification.
+- Quantization and placement are dynamic recipe inputs. The 2–4 and 10+ stage layouts are certification scenarios, never product constants.
+- Per-shard Hot KV and V4 CSA/HCA/SWA/indexer/compressor state remain local and keyed by route session/epoch. The WAN seam carries the typed mHC 4×4096 residual boundary, positions, token-ID sideband where required, and schema/cache expectations—not per-layer caches.
+- Route changes use cache miss plus re-prefill/restart. There is no WAN KV or V4 auxiliary-cache migration.
+- CPU/CUDA/ROCm/Vulkan/Metal compile lanes are planned; only exact real-hardware-certified backend/model/recipe lanes may be advertised.
+- Alpha requires correctness and the pre-locked useful-speed gate. MTP is reserved and off for alpha; its ownership contract, implementation, and benchmark are required before beta.
 
-Whole-model llama.cpp, vLLM, and existing Transformers serving remain baselines or optional route kinds. They are not substitutes for native distributed Shards.
+## Target identities
 
-## Performance hypothesis—not an assumption
+- DeepSeek V4 official target SHA: `60d8d70770c6776ff598c94bb586a859a38244f1`.
+- llama.cpp V4 support lineage began at PR 24162 / merge `8c146a8366304c871efc26057cc90370ccf58dad`; DGR-027 later pins one exact validated current commit.
+- V4 scope: 43 main layers plus MTP; mHC 4×4096 boundary; 256 routed + 1 shared experts with six routed active; token IDs required for the first three hash-routed layers.
+- Exact split-GGUF artifacts are provisioned to mounted-drive storage with a complete hashed manifest and resumable verification; no model artifact may be placed under `/home`.
 
-GGUF itself is a format. Performance comes from llama.cpp/GGML's quantized kernels, memory layout, mmap, backend scheduling, and reduced working set.
-
-Quantized GGUF may be faster or may merely fit a larger model. Comparisons against safetensors must report both speed and quality because BF16 safetensors and Q4/Q8 GGUF are not numerically equivalent.
-
-Before expensive native work, establish controlled lanes:
-
-- Same model architecture and upstream revision.
-- Same machine, prompt set, context, output length, sampling policy, and concurrency.
-- Transformers/safetensors BF16 or the current production recipe.
-- llama.cpp GGUF F16/BF16 or Q8 correctness lane where available.
-- Q4_K_M or selected production quantization performance/fit lane.
-- TTFT, prefill tok/s, decode tok/s, p50/p95 latency, RSS, VRAM, artifact size, energy where available, and output-quality drift.
-
-The program proceeds only if llama.cpp/GGUF provides at least one meaningful advantage recorded in a machine-readable performance contract:
-
-- Better decode or aggregate throughput at acceptable quality; or
-- Materially lower memory that makes the target model routable while preserving useful throughput.
-
-## Parallelism we will use
-
-### Public Inference Route: layer/pipeline parallelism
-
-Each node independently executes one contiguous Shard. Activations cross seams; weights and Hot KV State remain local.
-
-This is the only public cross-machine model-parallel primitive in the first runtime.
-
-### Per-node continuous batching
-
-Autoregressive tokens remain sequential within one generation. Throughput comes from batching decode steps from multiple active Route Sessions inside each node using llama.cpp batches and sequence IDs or bounded context pools.
-
-This is essential. A worker that globally serializes sessions is not production-ready.
-
-### Multiple complete routes: data parallelism
-
-The Tracker may select multiple complete routes for independent requests. This increases network throughput and availability without requiring collectives between routes.
-
-### Trusted composite node: optional tensor/expert parallelism
-
-Tensor parallelism and expert parallelism require frequent collectives and tight compatibility. They may be used later inside one operator-controlled composite node or managed cluster exposed as one logical provider. They are not public WAN routing primitives.
-
-### Deferred mechanisms
-
-- Disaggregated prefill and KV transfer.
-- Speculative decoding.
-- Cross-route prefix snapshots.
-- Route repair with KV migration.
-- Public tensor/expert parallel collectives.
-
-They remain out of the critical path until the native layer route passes performance and concurrency gates.
-
-## Reuse decisions
-
-### llama.cpp/GGML: primary runtime substrate
-
-Reuse:
-
-- GGUF parsing and mmap.
-- Quantized kernels.
-- CPU, CUDA, HIP/ROCm, Vulkan, Metal, and other supported backends.
-- Tokenizer and model architecture implementations.
-- KV and sequence operations.
-- Backend scheduler and graph execution.
-
-Maintain a small exact-commit fork only for the missing local seam:
-
-- Range-aware tensor ownership/loading.
-- Architecture-defined boundary input/output.
-- Intermediate boundary output without tail normalization.
-- Layer-filtered KV and sequence mapping.
-
-Keep networking, Tracker logic, billing, and public protocol outside llama.cpp. Upstream generic hooks where possible.
-
-### vLLM: concepts and optional managed backend
-
-Use unmodified vLLM only as:
-
-- A whole-model node backend.
-- A managed TP/PP/EP cluster represented as one logical provider.
-- A performance/correctness baseline.
-
-Adapt concepts, not runtime code:
-
-- Named intermediate tensor bundles.
-- Continuous batching and request-owner maps.
-- Versioned KV-transfer compatibility fingerprints.
-- Explicit send/receive/abort/failure lifecycle.
-- Load telemetry and unbiased route selection.
-
-Do not fork vLLM for public Shards and do not transplant PagedAttention, Torch process groups, or GGUF-plugin kernels into the llama.cpp worker.
-
-### Nakshatra, prima.cpp, llama-gguf, LiGGUF, GPUStack
-
-Use as source and test donors only:
-
-- Nakshatra: partial-GGUF patches, daemon concepts, replay cases.
-- prima.cpp: selected tensor ownership and local-layer KV evidence.
-- llama-gguf: small protocol and integration-test patterns.
-- LiGGUF: Q8 activation transport and tensor-reduction reference.
-- historical GPUStack: resource preflight and role-oriented placement.
-
-Do not adopt or fork their repositories wholesale.
-
-## Battle-proven transport decision
-
-Use gRPC over HTTP/2 with Protocol Buffers for the native C++ Shard worker protocol.
-
-Why:
-
-- Mature Python and C++ implementations.
-- Bidirectional streaming.
-- HTTP/2 flow control and connection reuse.
-- Deadlines, cancellation, status codes, TLS, authentication interceptors, and generated schemas.
-- Avoids inventing a socket protocol.
-
-Scope boundary:
-
-- OpenAI-compatible client/Gateway APIs remain HTTP/SSE.
-- Tracker/control APIs remain existing project interfaces.
-- One long-lived bidirectional gRPC stream serves one Route Session Activation Seam.
-- Existing relay/WebSocket infrastructure may carry the same versioned protobuf frames as opaque binary when direct gRPC reachability is unavailable.
-- Large prefill tensors are chunked into bounded frames; decode bundles stay small.
-- No QUIC/WebRTC/custom transport in this milestone.
-
-The public boundary uses a versioned named-tensor bundle rather than one anonymous tensor because architecture boundaries can require more than `hidden_states`.
-
-Minimum identity:
-
-```text
-schema version
-request/work id
-Route Session id and route epoch
-Model Artifact and runtime recipe fingerprint
-Shard range and effective start
-phase: prefill/decode/release/cancel
-position/token range
-named tensors with shape/dtype/byte order
-compression and checksum
-idempotency step id
-cache expectation/result
-```
-
-## Concurrency model
-
-A native worker must not use one global serving sequence or one lock around all model execution.
-
-Required ownership:
-
-```text
-(Route Session id, route epoch)
-    -> local sequence/context
-    -> Shard-local Hot KV State
-    -> bounded lease and memory accounting
-```
-
-The node scheduler:
-
-- Admits sessions against model memory and KV budget.
-- Forms compatible decode batches from active sessions.
-- Preserves per-session position and route order.
-- Applies bounded queues and backpressure.
-- Cancels/releases independently.
-- Reports queue, batch, KV, prefill, decode, and seam telemetry.
-
-Initial deterministic gate: at least four concurrent sessions on a small certified model with no token/KV cross-talk. Final concurrency targets are hardware/recipe-specific and recorded by capability admission rather than hardcoded globally.
-
-## Stage gates
-
-### Gate A: performance hypothesis
-
-Controlled safetensors-versus-GGUF benchmark produces a signed/reproducible report and locks thresholds. Stop native work if there is no meaningful speed or fit benefit.
-
-### Gate B: local range parity
-
-Two local processes own disjoint GGUF ranges and match whole-model llama.cpp within the certified numerical tolerance for prefill and greedy decode.
-
-### Gate C: concurrent KV
-
-Multiple Route Sessions prefill/decode concurrently with isolated local KV, bounded memory, cancellation, and release.
-
-### Gate D: real distributed route
-
-Two physical machines execute one model that uses both Shards. Synthetic activation tests do not satisfy this gate.
-
-### Gate E: consumer-hardware performance
-
-On certified consumer hardware, the GGUF route beats the current distributed safetensors route under the locked performance contract or enables a larger otherwise-unroutable model at useful measured speed.
-
-### Gate F: architecture expansion
-
-Only after dense Llama-family gates pass, add an explicit Qwen3/Qwen3-MoE adapter and certify it independently.
-
-## Scope discipline
-
-The following do not block the first production candidate:
-
-- New cryptocurrency/economics work.
-- New artifact P2P protocol.
-- QUIC or WebRTC.
-- vLLM fork.
-- Whole-repository Nakshatra/prima adoption.
-- Every GGUF architecture.
-- Automatic route repair.
-- Prefix snapshot migration.
-- Speculative decoding.
-- A large-model marketing demo before small-model parity and concurrency pass.
-
-Every optimization must preserve output contract, session isolation, cancellation, resource cleanup, capability admission, and per-node attribution.
+DGR-020 cannot use distributed results. DGR-054 does not depend on MTP. DGR-070 depends on DGR-066. Compile support and scenario success never imply general routability.

.scratch/distributed-gguf-runtime/issues/01-lock-the-safetensors-versus-gguf-performance-contract.md

@@ -1,68 +0,0 @@
-# 01 — Lock the safetensors-versus-GGUF performance contract
-
-Status: ready-for-agent
-
-## Mandatory fresh-session context
-
-- Read [RALPH-CONTEXT.md](../RALPH-CONTEXT.md) completely before changing code.
-- This issue is `DGR-001` in [prd.json](../prd.json).
-- Read the evidence README for every dependency listed below.
-- Inspect current code and `git status`; historical text and previous agent claims are not evidence.
-
-## Description
-
-As a runtime engineer, I need a controlled baseline so that GGUF work proceeds from measured speed, memory, and quality rather than reputation.
-
-## Baseline model target
-
-Use the same model on both sides of the comparison, with the closest practical low-footprint precision pair:
-
-- **safetensors:** `deepseek-ai/DeepSeek-V2-Lite-Chat` in **BF16**
-- **GGUF:** `second-state/DeepSeek-V2-Lite-Chat-GGUF` in **Q2_K** (~6.5GB)
-
-Keep the benchmark matrix explicit for **CPU** and **GPU** runs. Reserve smaller non-DeepSeek fallback models only for loader plumbing smoke tests if needed; they do not count as the DGR-001 architecture-aligned baseline.
-
-## Expected durable outputs
-
-- Benchmark harness and deterministic tests
-- evidence/DGR-001/performance-contract.json
-- Raw and summarized safetensors/GGUF benchmark evidence
-
-## Acceptance criteria
-
-- [ ] Benchmark the same model architecture/revision, machine, prompts, context lengths, output lengths, sampling policy, and concurrency across the current Transformers/safetensors recipe and whole-model llama.cpp recipes.
-- [ ] Separate correctness/quality lanes from quantized performance/fit lanes instead of claiming BF16 and Q4 are numerically equivalent.
-- [ ] Report TTFT, prefill tok/s, decode tok/s, p50/p95 latency, aggregate throughput, RSS, VRAM, artifact size, failures, and output drift in machine-readable JSON.
-- [ ] Add concurrency levels 1 and 4 where memory permits.
-- [ ] Write a versioned performance contract consumed by later release gates, including an explicit stop condition when llama.cpp/GGUF has no meaningful speed or fit benefit.
-- [ ] 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
-- [ ] Real-model execution is opt-in through MESHNET_ENABLE_REAL_INFERENCE_TESTS=1 and records exact artifact/runtime/hardware evidence
-- [ ] Model artifacts remain on the configured mounted-drive storage and never under /home
-- [ ] 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-001/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
-
-## Dependency handoff
-
-- None. This story may start immediately.
-
-## Finish contract
-
-- 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 `<promise>COMPLETE</promise>` only after the evidence handoff exists.
-
-## References
-
-- [Ralph execution context](../RALPH-CONTEXT.md)
-- [PRD](../PRD.md)
-- [Implementation strategy](../implementation-strategy.md)
-- [Current architecture](../architecture.md)
-- [Architecture decision](../../docs/adr/0024-distributed-gguf-runtime.md)

.scratch/distributed-gguf-runtime/issues/017-reconcile-and-clean-the-superseded-dgr-backlog.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-017: Reconcile and clean the superseded DGR backlog
+
+- **Status / triage:** completed; `passes: true`
+- **Execution mode:** `AFK`
+- **Milestone:** `M0`
+- **Dependencies:** None
+- **Blocks (derived):** `DGR-018`, `DGR-019`, `DGR-027`, `DGR-054`
+- **Labels:** `area:provenance`, `area:cleanup`, `type:audit`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/017-reconcile-and-clean-the-superseded-dgr-backlog.md`, and evidence READMEs for dependencies (none) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Audit implementation reality, void inherited completion credit, and clean misleading backlog/stub baggage while preserving attributable evidence and accepted research.
+
+## Acceptance criteria
+
+- [x] Compare the branch, old DGR-001..016 issue/pass states, evidence, and actual runtime sources; classify each output as reusable, reference-only, blocked, obsolete, or absent.
+- [x] Record an authoritative old-to-new disposition and provenance; explicitly give no completion credit to any new story and note absent implementation/evidence.
+- [x] Remove or archive only artifacts the audit proves obsolete while preserving accepted ADRs, useful research, raw benchmark evidence, and attributable reusable work.
+- [x] Protect ignored build workspaces, generated protobuf outputs, Ralph logs, and model artifacts from accidental commits, and document every retained legacy artifact.
+- [x] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Verified evidence: `.scratch/distributed-gguf-runtime/evidence/DGR-017/README.md`. Legacy evidence remains provenance only and grants no implementation completion credit.

.scratch/distributed-gguf-runtime/issues/018-define-canonical-ralph-and-gitea-metadata-schema.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-018: Define canonical Ralph and Gitea metadata schema
+
+- **Status / triage:** completed; `passes: true`
+- **Execution mode:** `AFK`
+- **Milestone:** `M0`
+- **Dependencies:** `DGR-017`
+- **Blocks (derived):** `DGR-021`, `DGR-025`
+- **Labels:** `area:planning`, `area:gitea`, `type:infrastructure`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/018-define-canonical-ralph-and-gitea-metadata-schema.md`, and evidence READMEs for dependencies (DGR-017) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Make `prd.json` the validated source from which Markdown and Gitea issues can later be generated losslessly.
+
+## Acceptance criteria
+
+- [x] Define fields for stable ID/title, labels, milestone, type, `dependsOn`, derived `blocks`, triage, evidence class, and hardware/model/upstream flags.
+- [x] Validate that all stories start `passes: false`, use known dependencies, and have unique stable IDs.
+- [x] Reject cycles, missing dependencies, mismatched generated `blocks`, duplicate titles/IDs, and generated artifacts claiming authority over `prd.json`.
+- [x] Add deterministic model-free tests for parse, validation, and generation round trips.
+- [x] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Verified evidence: `.scratch/distributed-gguf-runtime/evidence/DGR-018/README.md`. Legacy evidence remains provenance only and grants no implementation completion credit.

.scratch/distributed-gguf-runtime/issues/019-lock-alpha-and-beta-performance-contracts.md

@@ -0,0 +1,40 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-019: Lock alpha and beta performance contracts
+
+- **Status / triage:** specification only; `ready-for-human`; `passes: false`
+- **Execution mode:** `HITL`
+- **Milestone:** `M0`
+- **Dependencies:** `DGR-017`
+- **Blocks (derived):** `DGR-020`, `DGR-044`, `DGR-054`
+- **Labels:** `area:performance`, `type:contract`, `priority:p0`, `gate:hitl`, `ready-for-human`
+- **Evidence class:** `release`
+- **Hardware:** `required`
+- **Model:** `generic+deepseek-v4`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/019-lock-alpha-and-beta-performance-contracts.md`, and evidence READMEs for dependencies (DGR-017) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Freeze useful speed, correctness, memory-fit, and stop/go thresholds before implementation results are visible.
+
+## Acceptance criteria
+
+- [ ] Define controlled safetensors, whole-model GGUF, dense distributed GGUF, and V4 Flash distributed lanes with fixed prompts, context/output lengths, sampling, concurrency, hardware, and metrics.
+- [ ] Alpha requires correctness plus a human-approved useful-speed threshold; beta adds concurrency, long-context, failure, and sustained-throughput thresholds.
+- [ ] Separate quantization/model-fit gains from runtime, transport, batching, and kernel gains.
+- [ ] Treat quants and 2–4/10+ stage counts only as named certification scenarios; no product logic may hardcode them.
+- [ ] Lock thresholds and stop conditions in versioned machine-readable data before benchmark result ingestion.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-019/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/02-adopt-the-versioned-grpc-shard-protocol.md

@@ -1,59 +0,0 @@
-# 02 — Adopt the versioned gRPC Shard protocol
-
-Status: done
-
-## Mandatory fresh-session context
-
-- Read [RALPH-CONTEXT.md](../RALPH-CONTEXT.md) completely before changing code.
-- This issue is `DGR-002` in [prd.json](../prd.json).
-- Read the evidence README for every dependency listed below.
-- Inspect current code and `git status`; historical text and previous agent claims are not evidence.
-
-## Description
-
-As a node developer, I need a battle-proven streaming protocol so that Python and C++ Shards communicate without a custom socket protocol.
-
-## Expected durable outputs
-
-- packages/node/native/proto/shard_runtime.proto
-- Reproducible Python/C++ schema generation and build wiring
-- Protocol round-trip and compatibility tests
-- evidence/DGR-002/README.md
-
-## Acceptance criteria
-
-- [x] Add a Protocol Buffers schema for capability, health, session stream, release, and cancellation operations.
-- [x] Define one long-lived bidirectional gRPC stream per Route Session Activation Seam with deadlines, cancellation, flow control, and structured errors.
-- [x] Define bounded chunking for prefill and a small decode fast path.
-- [x] Carry schema version, request/work ID, Route Session ID, route epoch, artifact/recipe fingerprint, Shard range/effective start, phase, position, idempotency step, cache expectation, compression, and checksum.
-- [x] Define a versioned named-tensor bundle with per-tensor name, shape, dtype, byte order, and payload fragments.
-- [x] Add generated-schema round-trip and compatibility tests in Python and C++.
-- [x] Targeted pytest tests pass
-- [x] python -m compileall packages tests passes for Python changes
-- [x] git diff --check passes
-- [x] Default tests remain deterministic, model-download-free, API-credit-free, and GPU-free
-- [x] Full deterministic pytest -q passes, or the exact pre-existing unrelated failure is recorded with a clean-tree reproduction
-- [x] Read .scratch/distributed-gguf-runtime/RALPH-CONTEXT.md and this story issue completely before changing code
-- [x] Read and verify every dependency evidence README before relying on dependency behavior
-- [x] Preserve all pre-existing working-tree changes and stage only files belonging to this story
-- [x] Write .scratch/distributed-gguf-runtime/evidence/DGR-002/README.md with files changed, exact commands and real results, limitations, compatibility notes, and dependent-story handoff
-- [x] Update only this story issue to Status: done after every acceptance criterion and quality gate passes
-
-## Dependency handoff
-
-- None. This story may start immediately.
-
-## Finish contract
-
-- 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 `<promise>COMPLETE</promise>` only after the evidence handoff exists.
-
-## References
-
-- [Ralph execution context](../RALPH-CONTEXT.md)
-- [PRD](../PRD.md)
-- [Implementation strategy](../implementation-strategy.md)
-- [Current architecture](../architecture.md)
-- [Architecture decision](../../docs/adr/0024-distributed-gguf-runtime.md)

.scratch/distributed-gguf-runtime/issues/020-run-the-controlled-whole-model-gguf-baseline.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-020: Run the controlled whole-model GGUF baseline
+
+- **Status / triage:** specification only; `ready-for-human`; `passes: false`
+- **Execution mode:** `HITL`
+- **Milestone:** `M0`
+- **Dependencies:** `DGR-019`
+- **Blocks (derived):** `DGR-054`
+- **Labels:** `area:performance`, `type:benchmark`, `priority:p0`, `gate:hitl`, `ready-for-human`
+- **Evidence class:** `real-hardware`
+- **Hardware:** `required`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/020-run-the-controlled-whole-model-gguf-baseline.md`, and evidence READMEs for dependencies (DGR-019) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Execute the locked safetensors and whole-model llama.cpp lanes before distributed implementation results can influence the decision.
+
+## Acceptance criteria
+
+- [ ] Run the exact DGR-019 safetensors and whole-model llama.cpp benchmark lanes with locked prompts, lengths, sampling, concurrency, hardware, and artifact/runtime identities.
+- [ ] Record raw machine-readable correctness, TTFT, prefill/decode, throughput, latency, memory, artifact-size, failure, and quality-drift metrics without ingesting distributed implementation results.
+- [ ] Separate quantization/model-fit effects from runtime/kernel effects and preserve failed or unavailable lanes honestly.
+- [ ] Publish a threshold-based `go`, `optimize baseline`, or `stop` decision without changing the locked contract.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-020/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/021-define-the-versioned-named-tensor-stream-envelope.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-021: Define the versioned named-tensor stream envelope
+
+- **Status / triage:** completed; `passes: true`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-018`
+- **Blocks (derived):** `DGR-022`, `DGR-023`, `DGR-025`, `DGR-031`, `DGR-035`, `DGR-046`
+- **Labels:** `area:protocol`, `type:infrastructure`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/021-define-the-versioned-named-tensor-stream-envelope.md`, and evidence READMEs for dependencies (DGR-018) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Establish the backend-neutral protobuf envelope used by direct and relayed Shard activation traffic.
+
+## Acceptance criteria
+
+- [x] Define schema version, request/work ID, route session/epoch, shard range/effective start, phase, position, and idempotency step.
+- [x] Define named tensors with shape, dtype, byte order, bounded fragments, compression identity, and checksum.
+- [x] Reserve extensible fields for token-ID sidebands, architecture state, recurrent state, and MTP without claiming implementations.
+- [x] Add deterministic serialization, fragmentation, checksum, unknown-field, and size-limit tests.
+- [x] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Verified evidence: `.scratch/distributed-gguf-runtime/evidence/DGR-021/README.md`. Legacy evidence remains provenance only and grants no implementation completion credit.

.scratch/distributed-gguf-runtime/issues/022-define-shard-lifecycle-and-structured-status-rpcs.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-022: Define Shard lifecycle and structured status RPCs
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-021`
+- **Blocks (derived):** `DGR-024`, `DGR-033`, `DGR-037`
+- **Labels:** `area:protocol`, `area:lifecycle`, `type:infrastructure`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/022-define-shard-lifecycle-and-structured-status-rpcs.md`, and evidence READMEs for dependencies (DGR-021) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Complete the gRPC contract for worker capability, health, sessions, cancellation, release, and metrics.
+
+## Acceptance criteria
+
+- [ ] Define capability, health, bidirectional session stream, cancellation, release, and metrics RPCs.
+- [ ] Specify deadlines, cancellation propagation, bounded flow control, cache expectations/results, and structured error taxonomy.
+- [ ] Specify TLS/auth hooks without moving Meshnet authentication or billing into the worker.
+- [ ] Add compatibility tests for supported versions and fail-closed tests for unsupported versions and malformed lifecycle transitions.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-022/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/023-make-python-and-c-protobuf-generation-reproducible.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-023: Make Python and C++ protobuf generation reproducible
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-021`
+- **Blocks (derived):** `DGR-024`, `DGR-037`
+- **Labels:** `area:protocol`, `area:build`, `type:tooling`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/023-make-python-and-c-protobuf-generation-reproducible.md`, and evidence READMEs for dependencies (DGR-021) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Generate identical Python/C++ protocol bindings without manual copying or checked-in build debris.
+
+## Acceptance criteria
+
+- [ ] Pin protoc, gRPC, and plugin versions or declare a verified compatible range.
+- [ ] Generate Python and C++ bindings into out-of-tree build/package locations through documented commands.
+- [ ] Add Python↔C++ round-trip and descriptor compatibility tests.
+- [ ] A clean checkout regenerates bindings deterministically or fails with an actionable toolchain error.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-023/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/024-implement-in-memory-fake-grpc-seam-transport.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-024: Implement in-memory fake gRPC seam transport
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-022`, `DGR-023`
+- **Blocks (derived):** `DGR-033`, `DGR-042`
+- **Labels:** `area:protocol`, `area:testing`, `type:vertical-slice`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `fixture`
+- **Hardware:** `none`
+- **Model:** `fake`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/024-implement-in-memory-fake-grpc-seam-transport.md`, and evidence READMEs for dependencies (DGR-022, DGR-023) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Exercise the complete streaming protocol deterministically before a real model or worker exists.
+
+## Acceptance criteria
+
+- [ ] Provide a fake bidirectional stream supporting prefill fragments, decode fast-path frames, release, cancel, and structured errors.
+- [ ] Test flow-control blocking, deadlines, malformed fragments, checksum failure, duplicates, and stale epochs.
+- [ ] Verify direct and opaque-relay framing preserve identical protobuf bytes.
+- [ ] Tests require no sockets outside localhost, model downloads, or native accelerator.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-024/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/025-define-exact-artifact-and-runtime-recipe-identity.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-025: Define exact artifact and runtime recipe identity
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-018`, `DGR-021`
+- **Blocks (derived):** `DGR-026`, `DGR-031`, `DGR-041`, `DGR-044`
+- **Labels:** `area:identity`, `area:admission`, `type:domain`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/025-define-exact-artifact-and-runtime-recipe-identity.md`, and evidence READMEs for dependencies (DGR-018, DGR-021) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Ensure the tracker and worker only combine numerically and operationally compatible shards.
+
+## Acceptance criteria
+
+- [ ] Fingerprint source artifact SHA, tokenizer revision, architecture adapter/version, boundary schema, runtime pin/patch stack, backend, quant, activation/compute dtype, and KV/state layout.
+- [ ] Bind each shard to an exact half-open range without hardcoding a topology or quant.
+- [ ] Fail closed on any artifact, adapter, boundary, cache, backend, or runtime mismatch.
+- [ ] Unsupported recipes remain registered-but-dark until real-hardware evidence certifies them.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-025/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/026-provision-exact-split-gguf-artifacts-outside-home.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-026: Provision exact split-GGUF artifacts outside /home
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-025`
+- **Blocks (derived):** `DGR-044`, `DGR-045`
+- **Labels:** `area:artifacts`, `area:provenance`, `type:tooling`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `fixture`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/026-provision-exact-split-gguf-artifacts-outside-home.md`, and evidence READMEs for dependencies (DGR-025) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Make exact split-GGUF inputs reproducibly available from mounted-drive storage without embedding a quantization or topology assumption in product code.
+
+## Acceptance criteria
+
+- [ ] Create an exact manifest that binds the source artifact, tokenizer/revision, every split file name, size, range/role, and cryptographic hash.
+- [ ] Provide resumable, hash-verifying download/provision tooling targeting configured mounted-drive storage; refuse paths under `/home` and incomplete or mismatched splits.
+- [ ] Keep quantization and split topology as manifest/recipe inputs with no hardcoded quant, node count, or range layout.
+- [ ] Add deterministic model-download-free tests using tiny local split fixtures, including interrupted resume, missing split, hash mismatch, and `/home` rejection.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-026/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/027-add-exact-llama-cpp-provenance-manifest-and-fetch-workspace.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-027: Add exact llama.cpp provenance manifest and fetch workspace
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-017`
+- **Blocks (derived):** `DGR-028`, `DGR-029`, `DGR-044`
+- **Labels:** `area:upstream`, `area:build`, `type:provenance`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/027-add-exact-llama-cpp-provenance-manifest-and-fetch-workspace.md`, and evidence READMEs for dependencies (DGR-017) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Pin llama.cpp exactly through an in-repo manifest while fetching source only into an ignored build workspace.
+
+## Acceptance criteria
+
+- [ ] Manifest records upstream URL, exact commit, expected source archive/tree hash, license, and retrieval method.
+- [ ] Fetch tooling verifies identity before use and refuses an unpinned branch/tag.
+- [ ] Source is fetched into an ignored build workspace; no submodule, vendored source tree, or permanent fork is introduced.
+- [ ] Offline reuse is supported only after the cached tree’s exact identity is verified.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-027/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/028-implement-numbered-patch-stack-apply-and-verification.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-028: Implement numbered patch-stack apply and verification
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-027`
+- **Blocks (derived):** `DGR-029`, `DGR-034`, `DGR-069`
+- **Labels:** `area:upstream`, `area:patches`, `type:tooling`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/028-implement-numbered-patch-stack-apply-and-verification.md`, and evidence READMEs for dependencies (DGR-027) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Maintain a minimal auditable llama.cpp delta with one numbered patch per concern.
+
+## Acceptance criteria
+
+- [ ] Add deterministic apply/check/reverse verification against the exact manifest pin.
+- [ ] Separate range loading, boundary I/O, filtered state, and worker hooks into scoped patches.
+- [ ] Record upstream file/API assumptions and fail with the first incompatible patch when the pin changes.
+- [ ] Verify license/attribution and prove no Meshnet routing, billing, relay, or authentication code enters the patch stack.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-028/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/029-create-the-native-cmake-skeleton-and-deterministic-cpu-lane.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-029: Create the native CMake skeleton and deterministic CPU lane
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-027`, `DGR-028`
+- **Blocks (derived):** `DGR-030`, `DGR-034`
+- **Labels:** `area:build`, `type:toolchain`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/029-create-the-native-cmake-skeleton-and-deterministic-cpu-lane.md`, and evidence READMEs for dependencies (DGR-027, DGR-028) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Establish an out-of-tree standalone native build with a deterministic CPU lane before accelerator matrix work.
+
+## Acceptance criteria
+
+- [ ] Create the standalone native CMake target/skeleton and isolated out-of-tree configure/build preset for CPU.
+- [ ] Build and run a deterministic model-free CPU smoke/CTest lane from a clean checkout with actionable toolchain failures.
+- [ ] Keep fetched upstream sources, generated bindings, and all build outputs ignored and out of tree.
+- [ ] Ensure build success alone does not advertise any backend/model/recipe capability.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-029/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/03-define-exact-artifact-and-runtime-recipe-identity.md

@@ -1,57 +0,0 @@
-# 03 — Define exact Artifact and runtime recipe identity
-
-Status: done
-
-## Mandatory fresh-session context
-
-- Read [RALPH-CONTEXT.md](../RALPH-CONTEXT.md) completely before changing code.
-- This issue is `DGR-003` in [prd.json](../prd.json).
-- Read the evidence README for every dependency listed below.
-- Inspect current code and `git status`; historical text and previous agent claims are not evidence.
-
-## Description
-
-As the Tracker, I need exact compatibility identity so that only numerically and operationally compatible Shards form an Inference Route.
-
-## Expected durable outputs
-
-- Exact runtime recipe/fingerprint implementation
-- Tracker/node fail-closed admission tests
-- evidence/DGR-003/README.md
-
-## Acceptance criteria
-
-- [ ] Separate weight quantization, activation dtype, compute dtype, KV dtype/layout, tokenizer revision, architecture adapter, backend, and runtime version.
-- [ ] Bind derivative or split artifacts to an exact source Model Artifact hash and Shard range.
-- [ ] Produce a stable compatibility fingerprint used by capability admission and the gRPC handshake.
-- [ ] Fail closed on mismatched artifact, tokenizer, architecture, range, boundary schema, activation recipe, or cache layout.
-- [ ] Keep unsupported recipes registered-but-dark until a real distributed forward certifies them.
-- [ ] 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
-- [ ] 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-003/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
-
-## Dependency handoff
-
-- `DGR-002` must have `passes: true`; read `../evidence/DGR-002/README.md` and verify its referenced files/commands.
-
-## Finish contract
-
-- 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 `<promise>COMPLETE</promise>` only after the evidence handoff exists.
-
-## References
-
-- [Ralph execution context](../RALPH-CONTEXT.md)
-- [PRD](../PRD.md)
-- [Implementation strategy](../implementation-strategy.md)
-- [Current architecture](../architecture.md)
-- [Architecture decision](../../docs/adr/0024-distributed-gguf-runtime.md)

.scratch/distributed-gguf-runtime/issues/030-add-accelerator-build-presets-and-native-ci-matrix.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-030: Add accelerator build presets and native CI matrix
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-029`
+- **Blocks (derived):** `DGR-053`, `DGR-067`, `DGR-068`
+- **Labels:** `area:build`, `area:hardware`, `type:toolchain`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `optional`
+- **Model:** `generic`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/030-add-accelerator-build-presets-and-native-ci-matrix.md`, and evidence READMEs for dependencies (DGR-029) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Compile all required accelerator lanes reproducibly while keeping untested real-hardware capabilities registered-dark.
+
+## Acceptance criteria
+
+- [ ] Add isolated out-of-tree presets for CUDA, ROCm, Vulkan, and Metal without changing the deterministic CPU default.
+- [ ] Add a native CI/build matrix that reports unavailable SDKs as explicit unavailable/skipped lanes rather than false success.
+- [ ] Compile each available lane and preserve exact compiler, SDK, upstream pin, patch-stack, and build-option evidence.
+- [ ] Keep every backend/model/recipe lane registered-dark until a separate real-hardware certification record exists.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-030/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/031-introduce-the-project-owned-shardengine-interface.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-031: Introduce the project-owned `ShardEngine` interface
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-021`, `DGR-025`
+- **Blocks (derived):** `DGR-032`, `DGR-034`, `DGR-035`, `DGR-037`
+- **Labels:** `area:engine`, `type:architecture`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/031-introduce-the-project-owned-shardengine-interface.md`, and evidence READMEs for dependencies (DGR-021, DGR-025) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Isolate worker/protocol code from llama.cpp internals behind a stable project-owned engine contract.
+
+## Acceptance criteria
+
+- [ ] Define load, capabilities, prefill/decode, boundary/logits result, cancel, release, health, and metrics operations.
+- [ ] Use project-owned request/result/state types; expose no `ggml_tensor`, llama context, scheduler, or ABI-owned structure.
+- [ ] Reserve typed MTP and architecture auxiliary-state hooks without enabling them.
+- [ ] Add contract tests proving fake and future llama implementations obey identical lifecycle semantics.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-031/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/032-implement-deterministic-fake-shardengine.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-032: Implement deterministic fake `ShardEngine`
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-031`
+- **Blocks (derived):** `DGR-033`
+- **Labels:** `area:engine`, `area:testing`, `type:fixture`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `fixture`
+- **Hardware:** `none`
+- **Model:** `fake`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/032-implement-deterministic-fake-shardengine.md`, and evidence READMEs for dependencies (DGR-031) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Provide an engine fixture that deterministically transforms typed boundary bundles and session state.
+
+## Acceptance criteria
+
+- [ ] Support head, middle, tail, prefill, decode, cancellation, and release with deterministic outputs.
+- [ ] Model isolated session/epoch state and deterministic cache-miss/stale-epoch failures.
+- [ ] Support configurable delay, memory pressure, malformed output, and crash injection.
+- [ ] Contract tests distinguish fixture evidence from real-model certification.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-032/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/033-build-a-standalone-fake-c-grpc-shard-worker.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-033: Build a standalone fake C++ gRPC Shard worker
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-022`, `DGR-024`, `DGR-032`
+- **Blocks (derived):** `DGR-036`, `DGR-040`
+- **Labels:** `area:worker`, `area:grpc`, `type:vertical-slice`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `fixture`
+- **Hardware:** `none`
+- **Model:** `fake`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/033-build-a-standalone-fake-c-grpc-shard-worker.md`, and evidence READMEs for dependencies (DGR-022, DGR-024, DGR-032) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Prove the standalone worker process, stream, lifecycle, and supervision shape before llama.cpp integration.
+
+## Acceptance criteria
+
+- [ ] A standalone C++ executable serves the complete lifecycle and stream RPC contract using the fake engine.
+- [ ] Python integration tests cover startup, health, capability, fragmented prefill, decode, release, cancellation, and graceful shutdown.
+- [ ] Bounded messages, deadlines, flow control, and independent session cancellation are enforced.
+- [ ] The worker exposes neither llama.cpp RPC nor arbitrary graph execution.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-033/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/034-implement-dense-llama-range-aware-gguf-ownership.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-034: Implement dense-Llama range-aware GGUF ownership
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M2`
+- **Dependencies:** `DGR-028`, `DGR-029`, `DGR-031`
+- **Blocks (derived):** `DGR-035`, `DGR-037`, `DGR-051`
+- **Labels:** `area:llama`, `area:weights`, `type:runtime`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `optional`
+- **Model:** `dense-llama`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/034-implement-dense-llama-range-aware-gguf-ownership.md`, and evidence READMEs for dependencies (DGR-028, DGR-029, DGR-031) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Load only the dense-Llama tensors owned by a shard range.
+
+## Acceptance criteria
+
+- [ ] Load only `blk.N.*` tensors in the assigned range, embeddings only at the head, and norm/output or tied output only at the tail.
+- [ ] Derive authoritative range and endpoint ownership from the loaded engine state.
+- [ ] Reject invalid/gapped/out-of-model ranges and unexpected required tensors.
+- [ ] Real-model evidence shows mapped/resident memory scales with owned tensors rather than full artifact size.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-034/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/035-implement-dense-architecture-boundary-input-output.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-035: Implement dense architecture boundary input/output
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M2`
+- **Dependencies:** `DGR-021`, `DGR-031`, `DGR-034`
+- **Blocks (derived):** `DGR-036`, `DGR-037`, `DGR-069`
+- **Labels:** `area:llama`, `area:boundary`, `type:runtime`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `optional`
+- **Model:** `dense-llama`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/035-implement-dense-architecture-boundary-input-output.md`, and evidence READMEs for dependencies (DGR-021, DGR-031, DGR-034) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Execute dense head/middle/tail ranges through an architecture-defined residual boundary.
+
+## Acceptance criteria
+
+- [ ] Head accepts token IDs and owns embedding; middle/tail bypass embedding and accept a named boundary bundle.
+- [ ] Non-tail returns the unnormalized residual before final norm/head and before tail-only row pruning.
+- [ ] Tail returns logits or sampled-token output under an explicit contract.
+- [ ] Uncertified architectures and incompatible boundary schemas fail closed.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-035/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/036-prove-dense-fixture-and-real-model-range-parity.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-036: Prove dense fixture and real-model range parity
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M2`
+- **Dependencies:** `DGR-033`, `DGR-035`
+- **Blocks (derived):** `DGR-039`
+- **Labels:** `area:parity`, `area:testing`, `type:certification`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `optional`
+- **Model:** `dense-llama`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/036-prove-dense-fixture-and-real-model-range-parity.md`, and evidence READMEs for dependencies (DGR-033, DGR-035) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Prove the engine/protocol seam before adding session concurrency.
+
+## Acceptance criteria
+
+- [ ] Model-free two-stage tests pass through two fake worker processes with disjoint ranges.
+- [ ] A small real dense GGUF passes whole-model versus two-range prefill parity.
+- [ ] At least 32 greedy decode tokens match the locked tolerance.
+- [ ] Evidence distinguishes deterministic fixture proof from opt-in real-model proof.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-036/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/037-bind-llama-cpp-to-the-standalone-worker.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-037: Bind llama.cpp to the standalone worker
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M2`
+- **Dependencies:** `DGR-022`, `DGR-023`, `DGR-031`, `DGR-034`, `DGR-035`
+- **Blocks (derived):** `DGR-038`, `DGR-039`, `DGR-040`, `DGR-051`
+- **Labels:** `area:worker`, `area:llama`, `type:vertical-slice`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `optional`
+- **Model:** `dense-llama`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/037-bind-llama-cpp-to-the-standalone-worker.md`, and evidence READMEs for dependencies (DGR-022, DGR-023, DGR-031, DGR-034, DGR-035) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Replace the fake engine with the pinned llama.cpp `ShardEngine` implementation without changing the public worker contract.
+
+## Acceptance criteria
+
+- [ ] Worker loads exactly one artifact/recipe/range identity and rejects mismatched stream requests.
+- [ ] All execution passes through `ShardEngine`; llama.cpp implementation types remain private.
+- [ ] Health and metrics expose loaded identity, authoritative ownership, memory, and execution state.
+- [ ] Graceful shutdown releases model/session resources; injected process death is observable and bounded.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-037/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/038-implement-isolated-shard-local-hot-kv-state.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-038: Implement isolated shard-local Hot KV State
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M2`
+- **Dependencies:** `DGR-037`
+- **Blocks (derived):** `DGR-039`, `DGR-052`, `DGR-055`, `DGR-069`
+- **Labels:** `area:kv-cache`, `area:concurrency`, `type:runtime`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `optional`
+- **Model:** `dense-llama`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/038-implement-isolated-shard-local-hot-kv-state.md`, and evidence READMEs for dependencies (DGR-037) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Map each route session and epoch to isolated state containing only locally owned layers.
+
+## Acceptance criteria
+
+- [ ] Map `(route_session_id, route_epoch)` to an isolated llama sequence or bounded context.
+- [ ] Support prefill/decode append, truncate, release, TTL/LRU eviction, cache miss, and stale-epoch rejection.
+- [ ] Four concurrent sessions complete without token, KV, position, or cancellation cross-talk.
+- [ ] Release/eviction returns memory to the configured budget without affecting other sessions.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-038/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/039-pass-local-two-process-dense-acceptance.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-039: Pass local two-process dense acceptance
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M2`
+- **Dependencies:** `DGR-036`, `DGR-037`, `DGR-038`
+- **Blocks (derived):** `DGR-054`
+- **Labels:** `area:integration`, `area:parity`, `type:certification`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `optional`
+- **Model:** `dense-llama`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/039-pass-local-two-process-dense-acceptance.md`, and evidence READMEs for dependencies (DGR-036, DGR-037, DGR-038) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Establish the first real, independently executing distributed GGUF route on one host.
+
+## Acceptance criteria
+
+- [ ] Two worker processes open disjoint dense ranges and both execute real prefill/decode work.
+- [ ] Whole-model parity, 32-token greedy decode, four-session isolation, cancellation, and cleanup pass.
+- [ ] Record TTFT, prefill/decode rates, seam bytes/latency, RSS/VRAM, KV, queue, and failure metrics.
+- [ ] Killing one worker returns a bounded structured failure rather than hanging.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-039/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/04-create-the-reproducible-pinned-llama-cpp-patch-stack.md

@@ -1,61 +0,0 @@
-# 04 — Create the reproducible pinned llama.cpp patch stack
-
-Status: done
-
-## 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).
-- Read the evidence README for every dependency listed below.
-- Inspect current code and `git status`; historical text and previous agent claims are not evidence.
-
-## Description
-
-As a maintainer, I need a small auditable fork boundary so that upstream updates do not turn the runtime into an unmaintainable stitched codebase.
-
-## Expected durable outputs
-
-- Exact llama.cpp upstream pin
-- Numbered minimal patch stack
-- Reproducible fetch/apply/build smoke
-- evidence/DGR-004/README.md
-
-## Acceptance criteria
-
-- [ ] 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.
-- [ ] 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
-
-## Dependency handoff
-
-- `DGR-001` must have `passes: true`; read `../evidence/DGR-001/README.md` and verify its referenced files/commands.
-
-## Finish contract
-
-- 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 `<promise>COMPLETE</promise>` only after the evidence handoff exists.
-
-## References
-
-- [Ralph execution context](../RALPH-CONTEXT.md)
-- [PRD](../PRD.md)
-- [Implementation strategy](../implementation-strategy.md)
-- [Current architecture](../architecture.md)
-- [Architecture decision](../../docs/adr/0024-distributed-gguf-runtime.md)

.scratch/distributed-gguf-runtime/issues/040-add-node-side-native-worker-supervision.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-040: Add node-side native worker supervision
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M2`
+- **Dependencies:** `DGR-033`, `DGR-037`
+- **Blocks (derived):** `DGR-041`, `DGR-042`, `DGR-055`, `DGR-058`
+- **Labels:** `area:node`, `area:supervision`, `type:integration`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `fixture`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/040-add-node-side-native-worker-supervision.md`, and evidence READMEs for dependencies (DGR-033, DGR-037) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Let the existing node service safely start, probe, stop, and restart the standalone worker.
+
+## Acceptance criteria
+
+- [ ] Supervision owns process startup, readiness, log capture, graceful shutdown, and bounded forced termination.
+- [ ] Startup verifies worker binary, artifact identity, recipe, and range before registration.
+- [ ] Crashes or health loss make the capability unavailable without corrupting the Transformers backend.
+- [ ] Tests use the fake worker and deterministic crash injection.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-040/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/041-register-native-shard-capabilities-without-redesigning-meshnet.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-041: Register native Shard capabilities without redesigning Meshnet
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M2`
+- **Dependencies:** `DGR-025`, `DGR-040`
+- **Blocks (derived):** `DGR-043`
+- **Labels:** `area:meshnet`, `area:admission`, `type:integration`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/041-register-native-shard-capabilities-without-redesigning-meshnet.md`, and evidence READMEs for dependencies (DGR-025, DGR-040) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Adapt native worker identity and capacity to existing backend-agnostic capability admission.
+
+## Acceptance criteria
+
+- [ ] Registration carries exact recipe fingerprint, authoritative range, backend, memory/KV capacity, concurrency, and certification status.
+- [ ] Existing tracker, billing, routing, telemetry, and provider semantics remain backend-agnostic.
+- [ ] Uncertified backend/model/recipe combinations are visible but unroutable.
+- [ ] Existing Transformers registration and route tests remain unchanged in behavior.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-041/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/042-carry-native-frames-through-direct-and-existing-relay-seams.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-042: Carry native frames through direct and existing relay seams
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M2`
+- **Dependencies:** `DGR-024`, `DGR-040`
+- **Blocks (derived):** `DGR-054`, `DGR-058`
+- **Labels:** `area:meshnet`, `area:relay`, `area:grpc`, `type:integration`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `fixture`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/042-carry-native-frames-through-direct-and-existing-relay-seams.md`, and evidence READMEs for dependencies (DGR-024, DGR-040) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Use direct gRPC where available and the existing relay as opaque protobuf transport without redesigning relay behavior.
+
+## Acceptance criteria
+
+- [ ] Direct paths use the long-lived gRPC activation stream.
+- [ ] Relayed paths carry byte-identical versioned protobuf frames through the existing relay contract.
+- [ ] Request/work identity, cancellation, deadlines, telemetry, billing correlation, and per-node attribution survive both paths.
+- [ ] Fake-worker tests cover direct, relay, disconnect, cancellation, and bounded buffering.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-042/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/043-expose-gguf-compatibility-and-measured-cost-inputs-to-existing-routing.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-043: Expose GGUF compatibility and measured cost inputs to existing routing
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M2`
+- **Dependencies:** `DGR-041`
+- **Blocks (derived):** `DGR-053`, `DGR-054`, `DGR-059`, `DGR-061`
+- **Labels:** `area:tracker`, `area:routing`, `type:integration`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/043-expose-gguf-compatibility-and-measured-cost-inputs-to-existing-routing.md`, and evidence READMEs for dependencies (DGR-041) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Adapt exact GGUF recipe/range compatibility and measured capacity, queue, seam-cost, health, and reliability data into the existing backend-agnostic routing inputs without redesigning routing or load balancing.
+
+## Acceptance criteria
+
+- [ ] Expose exact recipe, range coverage, capacity, queue/load, seam-cost, health, reliability, backend, and certification measurements through existing tracker input contracts.
+- [ ] Prove existing routing forms complete compatible coverage and excludes dark or mismatched candidates using its current backend-agnostic mechanisms.
+- [ ] Regression-test unchanged Transformers behavior and unchanged tracker routing, load-balancing, billing, relay, and provider semantics.
+- [ ] Regression-test that no quant, stage count, fixed split, architecture, backend sequence, or DeepSeek-specific policy is hardcoded.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-043/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/044-pin-the-deepseek-v4-flash-target-contract.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-044: Pin the DeepSeek V4 Flash target contract
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M3`
+- **Dependencies:** `DGR-019`, `DGR-025`, `DGR-026`, `DGR-027`
+- **Blocks (derived):** `DGR-045`
+- **Labels:** `area:deepseek-v4`, `area:provenance`, `type:contract`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/044-pin-the-deepseek-v4-flash-target-contract.md`, and evidence READMEs for dependencies (DGR-019, DGR-025, DGR-026, DGR-027) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Fix the alpha/beta model identity and upstream maturity assumptions before implementing the adapter.
+
+## Acceptance criteria
+
+- [ ] Pin Hugging Face target SHA `60d8d70770c6776ff598c94bb586a859a38244f1`.
+- [ ] Record the selected GGUF provenance and exact source binding without assuming one quant.
+- [ ] Record that llama.cpp support began with PR 24162/commit `8c146a8` and remains maturing; the build manifest still pins one exact validated upstream commit.
+- [ ] Record 43 main layers plus MTP and all known architecture-specific state obligations.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-044/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/045-inventory-v4-gguf-tensors-and-layer-ownership.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-045: Inventory V4 GGUF tensors and layer ownership
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M3`
+- **Dependencies:** `DGR-026`, `DGR-044`
+- **Blocks (derived):** `DGR-046`, `DGR-047`, `DGR-050`
+- **Labels:** `area:deepseek-v4`, `area:weights`, `type:research-spike`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `none`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/045-inventory-v4-gguf-tensors-and-layer-ownership.md`, and evidence READMEs for dependencies (DGR-026, DGR-044) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Derive exact head, repeated-layer, tail, expert, auxiliary-state, and MTP ownership from the pinned artifact.
+
+## Acceptance criteria
+
+- [ ] Produce a machine-readable inventory tied to the target SHA and exact GGUF artifact.
+- [ ] Classify embeddings, 43 main layers, final head, MTP, mHC, attention variants, indexer/compressor, and MoE tensors.
+- [ ] Validate half-open range ownership and fail on unclassified required tensors.
+- [ ] Inventory tooling works across quants without embedding quant names in architecture logic.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-045/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/046-define-the-v4-typed-architecture-boundary-schema.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-046: Define the V4 typed architecture boundary schema
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M3`
+- **Dependencies:** `DGR-021`, `DGR-045`
+- **Blocks (derived):** `DGR-047`, `DGR-048`, `DGR-049`
+- **Labels:** `area:deepseek-v4`, `area:boundary`, `type:protocol`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/046-define-the-v4-typed-architecture-boundary-schema.md`, and evidence READMEs for dependencies (DGR-021, DGR-045) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Define the exact cross-stage V4 architecture boundary while keeping per-layer attention and auxiliary caches shard-local.
+
+## Acceptance criteria
+
+- [ ] Define a versioned named bundle for the mHC 4×4096 residual boundary, positions, token-ID sideband where required, and schema/cache expectations.
+- [ ] Explicitly exclude per-layer CSA, HCA, SWA, indexer, compressor, KV, and MTP caches/state from the WAN boundary; those remain local to the owning shard and session/epoch.
+- [ ] Reserve typed MTP boundary fields but mark MTP execution unsupported and unroutable for alpha.
+- [ ] Fingerprint independently of quant/topology and fail closed on missing, incompatible, incorrectly shaped, or stale boundary/cache expectations.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-046/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/047-adapt-the-upstream-v4-mhc-boundary-for-ranged-ownership.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-047: Adapt the upstream V4 mHC boundary for ranged ownership
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M3`
+- **Dependencies:** `DGR-045`, `DGR-046`
+- **Blocks (derived):** `DGR-048`, `DGR-049`, `DGR-050`, `DGR-051`
+- **Labels:** `area:deepseek-v4`, `area:mhc`, `type:runtime`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `optional`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/047-adapt-the-upstream-v4-mhc-boundary-for-ranged-ownership.md`, and evidence READMEs for dependencies (DGR-045, DGR-046) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Add range-boundary adapters around upstream llama.cpp V4 mHC execution without reimplementing the V4 graph or kernels.
+
+## Acceptance criteria
+
+- [ ] Represent and validate the upstream V4 4×4096 mHC boundary without flattening semantic axes.
+- [ ] Add only head/intermediate/tail range ownership and boundary conversion hooks around the pinned upstream llama.cpp graph.
+- [ ] Compare deterministic fixture vectors and single-process ranged outputs with upstream whole-model execution.
+- [ ] Document that llama.cpp owns V4 mHC graph/kernels and that quantized storage does not alter the logical boundary schema.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-047/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/048-carry-token-id-sideband-through-the-first-three-hash-routed-layers.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-048: Carry token-ID sideband through the first three hash-routed layers
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M3`
+- **Dependencies:** `DGR-046`, `DGR-047`
+- **Blocks (derived):** `DGR-051`
+- **Labels:** `area:deepseek-v4`, `area:routing-state`, `type:runtime`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `optional`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/048-carry-token-id-sideband-through-the-first-three-hash-routed-layers.md`, and evidence READMEs for dependencies (DGR-046, DGR-047) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Ensure any stage containing the first three hash-routed layers receives exact token identities.
+
+## Acceptance criteria
+
+- [ ] Head emits token IDs in the typed sideband for boundaries that require them.
+- [ ] Intermediate stages preserve or consume the sideband according to their layer range.
+- [ ] Routes splitting before, within, and after the first three layers pass deterministic partition tests.
+- [ ] Missing or mismatched token IDs fail closed rather than silently selecting incorrect experts.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-048/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/049-keep-v4-attention-and-auxiliary-state-shard-local.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-049: Keep V4 attention and auxiliary state shard-local
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M3`
+- **Dependencies:** `DGR-046`, `DGR-047`
+- **Blocks (derived):** `DGR-051`
+- **Labels:** `area:deepseek-v4`, `area:attention`, `type:runtime`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `optional`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/049-keep-v4-attention-and-auxiliary-state-shard-local.md`, and evidence READMEs for dependencies (DGR-046, DGR-047) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Bind V4 CSA/HCA/SWA/indexer/compressor and KV state to the owning shard session/epoch rather than transferring caches over the WAN.
+
+## Acceptance criteria
+
+- [ ] Map CSA, HCA, SWA, indexer, compressor, and KV ownership from the pinned upstream graph to each owned layer range.
+- [ ] Key all such caches/state by route session and epoch with bounded lifecycle, memory accounting, stale-epoch rejection, release, and eviction.
+- [ ] Prove cross-stage messages carry only the typed architecture boundary and cache expectations, never per-layer cache contents.
+- [ ] On route change or state loss, use explicit cache miss and re-prefill/restart; do not migrate V4 caches across workers.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-049/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/05-implement-dense-llama-range-aware-gguf-ownership.md

@@ -1,61 +0,0 @@
-# 05 — Implement dense-Llama range-aware GGUF ownership
-
-Status: done
-
-## Mandatory fresh-session context
-
-- Read [RALPH-CONTEXT.md](../RALPH-CONTEXT.md) completely before changing code.
-- This issue is `DGR-005` in [prd.json](../prd.json).
-- Read the evidence README for every dependency listed below.
-- Inspect current code and `git status`; historical text and previous agent claims are not evidence.
-
-## Description
-
-As a node, I need to map only my assigned dense-Llama Shard so that aggregate consumer memory can hold a model larger than one node.
-
-## Expected durable outputs
-
-- Dense-Llama range-aware ownership implementation
-- Authoritative loaded-range introspection
-- Mapped/resident memory evidence
-- evidence/DGR-005/README.md
-
-## Acceptance criteria
-
-- [ ] 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.
-- [ ] 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-005/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
-
-## Dependency handoff
-
-- `DGR-003` must have `passes: true`; read `../evidence/DGR-003/README.md` and verify its referenced files/commands.
-- `DGR-004` must have `passes: true`; read `../evidence/DGR-004/README.md` and verify its referenced files/commands.
-
-## Finish contract
-
-- 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 `<promise>COMPLETE</promise>` only after the evidence handoff exists.
-
-## References
-
-- [Ralph execution context](../RALPH-CONTEXT.md)
-- [PRD](../PRD.md)
-- [Implementation strategy](../implementation-strategy.md)
-- [Current architecture](../architecture.md)
-- [Architecture decision](../../docs/adr/0024-distributed-gguf-runtime.md)

.scratch/distributed-gguf-runtime/issues/050-validate-upstream-v4-moe-and-hash-routing-execution-under-ranged-ownership.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-050: Validate upstream V4 MoE and hash-routing execution under ranged ownership
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M3`
+- **Dependencies:** `DGR-045`, `DGR-047`
+- **Blocks (derived):** `DGR-051`
+- **Labels:** `area:deepseek-v4`, `area:moe`, `type:runtime`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `optional`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/050-validate-upstream-v4-moe-and-hash-routing-execution-under-ranged-ownership.md`, and evidence READMEs for dependencies (DGR-045, DGR-047) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Validate the pinned upstream llama.cpp V4 MoE and hash-routing graph when layers are range-owned, without reimplementing routing or expert kernels in Meshnet.
+
+## Acceptance criteria
+
+- [ ] Load range-owned tensors for 256 routed plus one shared expert and validate upstream execution activates six routed experts where specified.
+- [ ] Validate the first three upstream hash-routed layers receive exact token-ID sideband across splits before, within, and after them.
+- [ ] Compare upstream whole-model and ranged router/expert outputs, shared-expert contribution, and malformed sideband failures.
+- [ ] Document that llama.cpp owns V4 MoE, attention, hash routing, graph, and kernels; no expert-parallel WAN collective or Meshnet reimplementation is introduced.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-050/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/051-assemble-the-deepseek-v4-flash-shardengine-adapter.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-051: Assemble the DeepSeek V4 Flash `ShardEngine` adapter
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M3`
+- **Dependencies:** `DGR-034`, `DGR-037`, `DGR-047`, `DGR-048`, `DGR-049`, `DGR-050`
+- **Blocks (derived):** `DGR-052`, `DGR-060`, `DGR-065`, `DGR-069`
+- **Labels:** `area:deepseek-v4`, `area:engine`, `type:vertical-slice`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `optional`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/051-assemble-the-deepseek-v4-flash-shardengine-adapter.md`, and evidence READMEs for dependencies (DGR-034, DGR-037, DGR-047, DGR-048, DGR-049, DGR-050) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Assemble range ownership hooks and boundary/local-state adapters around upstream llama.cpp V4 execution behind the stable ShardEngine interface.
+
+## Acceptance criteria
+
+- [ ] Support valid head, middle, tail, and whole-model ranges over all 43 main layers using the pinned upstream llama.cpp V4 graph/kernels.
+- [ ] Integrate exact range ownership, mHC boundary, positions, required token-ID sideband, and shard-local session/epoch state adapters.
+- [ ] Report MTP reserved-but-not-executable for alpha and reject unsupported split points or cache expectations.
+- [ ] Include exact adapter/schema/runtime/artifact identity and valid split restrictions without reimplementing V4 MoE, attention, mHC, or hash routing.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-051/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/052-pass-local-v4-whole-model-versus-ranged-parity.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-052: Pass local V4 whole-model versus ranged parity
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M3`
+- **Dependencies:** `DGR-038`, `DGR-051`
+- **Blocks (derived):** `DGR-053`, `DGR-054`
+- **Labels:** `area:deepseek-v4`, `area:parity`, `type:certification`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `optional`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/052-pass-local-v4-whole-model-versus-ranged-parity.md`, and evidence READMEs for dependencies (DGR-038, DGR-051) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Prove V4 prefill and decode correctness locally before network certification.
+
+## Acceptance criteria
+
+- [ ] Compare pinned whole-model llama.cpp with at least two valid ranged partitions.
+- [ ] Prefill intermediates and locked-length greedy decode pass architecture-specific tolerances.
+- [ ] Test splits around the first three hash-routed layers and at least one CSA/HCA/SWA/indexer/compressor transition.
+- [ ] Four concurrent sessions pass KV/state isolation and cleanup.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-052/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/053-certify-a-real-2-4-stage-v4-route.md

@@ -0,0 +1,40 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-053: Certify a real 2–4-stage V4 route
+
+- **Status / triage:** specification only; `ready-for-human`; `passes: false`
+- **Execution mode:** `HITL`
+- **Milestone:** `M3`
+- **Dependencies:** `DGR-030`, `DGR-043`, `DGR-052`
+- **Blocks (derived):** `DGR-054`, `DGR-062`, `DGR-067`
+- **Labels:** `area:deepseek-v4`, `area:hardware`, `type:certification`, `priority:p0`, `gate:hitl`, `ready-for-human`
+- **Evidence class:** `real-hardware`
+- **Hardware:** `required`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/053-certify-a-real-2-4-stage-v4-route.md`, and evidence READMEs for dependencies (DGR-030, DGR-043, DGR-052) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Prove real Tracker-selected V4 execution across physical machines before alpha.
+
+## Acceptance criteria
+
+- [ ] Run one documented 2–4-stage certification scenario using exact compatible artifacts/recipes; the count and chosen quant are evidence inputs, not product constants.
+- [ ] Actual CPU/GPU work executes on every stage; fake workers do not satisfy acceptance.
+- [ ] Record parity, TTFT, prefill/decode speed, seam cost, memory, cache/state isolation, cancellation, and cleanup.
+- [ ] Tracker selection remains dynamic and rejects an injected incompatible backend/recipe.
+- [ ] Only the exact real-hardware lanes exercised become eligible for advertisement.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-053/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/054-enforce-the-deepseek-v4-flash-alpha-gate.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-054: Enforce the DeepSeek V4 Flash alpha gate
+
+- **Status / triage:** specification only; `ready-for-human`; `passes: false`
+- **Execution mode:** `HITL`
+- **Milestone:** `M3`
+- **Dependencies:** `DGR-017`, `DGR-019`, `DGR-020`, `DGR-039`, `DGR-042`, `DGR-043`, `DGR-052`, `DGR-053`
+- **Blocks (derived):** `DGR-055`, `DGR-065`, `DGR-066`, `DGR-068`
+- **Labels:** `area:deepseek-v4`, `area:release`, `milestone:alpha`, `priority:p0`, `gate:hitl`, `ready-for-human`
+- **Evidence class:** `release`
+- **Hardware:** `required`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/054-enforce-the-deepseek-v4-flash-alpha-gate.md`, and evidence READMEs for dependencies (DGR-017, DGR-019, DGR-020, DGR-039, DGR-042, DGR-043, DGR-052, DGR-053) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Release alpha only when V4 is correct and clears the pre-locked useful-speed requirement.
+
+## Acceptance criteria
+
+- [ ] Evaluate correctness, model fit, TTFT, prefill/decode speed, seam cost, memory, and failure rate against DGF-004 without changing thresholds.
+- [ ] Separate quant/model-fit gains from runtime/transport gains.
+- [ ] Decision is `alpha`, `optimize measured bottleneck`, or `stop`; failures cannot be relabeled as certification.
+- [ ] Alpha documentation states MTP is reserved but not implemented and identifies every dark hardware lane.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-054/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/055-implement-compatible-continuous-decode-batching.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-055: Implement compatible continuous decode batching
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M4`
+- **Dependencies:** `DGR-038`, `DGR-040`, `DGR-054`
+- **Blocks (derived):** `DGR-056`, `DGR-057`
+- **Labels:** `area:scheduler`, `area:batching`, `type:performance`, `priority:p1`, `ready-for-agent`
+- **Evidence class:** `fixture`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/055-implement-compatible-continuous-decode-batching.md`, and evidence READMEs for dependencies (DGR-038, DGR-040, DGR-054) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Batch compatible active sessions without violating route, recipe, position, or architecture state.
+
+## Acceptance criteria
+
+- [ ] Batch only sessions with compatible engine, recipe, phase, boundary schema, and state layout.
+- [ ] Preserve per-session positions, sequence IDs, outputs, cancellation, and accounting.
+- [ ] Decode receives bounded service while prefill remains schedulable.
+- [ ] Deterministic 1/2/4/8 concurrency tests show no cross-session corruption.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-055/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/056-enforce-bounded-admission-queues-and-backpressure.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-056: Enforce bounded admission, queues, and backpressure
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M4`
+- **Dependencies:** `DGR-055`
+- **Blocks (derived):** `DGR-057`, `DGR-058`, `DGR-060`
+- **Labels:** `area:scheduler`, `area:backpressure`, `type:performance`, `priority:p1`, `ready-for-agent`
+- **Evidence class:** `fixture`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/056-enforce-bounded-admission-queues-and-backpressure.md`, and evidence READMEs for dependencies (DGR-055) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Prevent weight, KV, state, scratch, and stream buffers from exceeding admitted capacity.
+
+## Acceptance criteria
+
+- [ ] Admission accounts separately for weights, KV/state, scratch, in-flight fragments, and queue slots.
+- [ ] Queue and stream limits produce structured retryable or terminal responses.
+- [ ] Prefill cannot starve decode and one route session cannot monopolize queue capacity.
+- [ ] Telemetry reports active sessions, queue depth/time, batch occupancy, memory pressure, and rejects.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-056/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/057-benchmark-batching-saturation-and-fairness.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-057: Benchmark batching saturation and fairness
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M4`
+- **Dependencies:** `DGR-055`, `DGR-056`
+- **Blocks (derived):** `DGR-061`, `DGR-063`, `DGR-070`
+- **Labels:** `area:performance`, `area:batching`, `type:benchmark`, `priority:p1`, `ready-for-agent`
+- **Evidence class:** `real-hardware`
+- **Hardware:** `required`
+- **Model:** `dense-llama+deepseek-v4`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/057-benchmark-batching-saturation-and-fairness.md`, and evidence READMEs for dependencies (DGR-055, DGR-056) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Identify useful concurrency and saturation points without assuming one global batch size.
+
+## Acceptance criteria
+
+- [ ] Run controlled concurrency 1/2/4/8 and record aggregate throughput, per-request p50/p95, TTFT, queue time, occupancy, and memory.
+- [ ] Measure dense and V4 lanes separately where hardware permits.
+- [ ] Verify bounded fairness and no prefill/decode starvation.
+- [ ] Produce machine-readable saturation recommendations consumed by capability reporting, not hardcoded constants.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-057/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/058-harden-worker-and-stream-failure-semantics.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-058: Harden worker and stream failure semantics
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M4`
+- **Dependencies:** `DGR-040`, `DGR-042`, `DGR-056`
+- **Blocks (derived):** `DGR-059`, `DGR-060`, `DGR-061`
+- **Labels:** `area:reliability`, `area:failure`, `type:hardening`, `priority:p1`, `ready-for-agent`
+- **Evidence class:** `fixture`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/058-harden-worker-and-stream-failure-semantics.md`, and evidence READMEs for dependencies (DGR-040, DGR-042, DGR-056) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Ensure malformed input, process death, transport reset, and cancellation terminate cleanly.
+
+## Acceptance criteria
+
+- [ ] Test worker death, stream reset, malformed bundle, checksum failure, deadline, cache miss, stale epoch, and partial fragment loss.
+- [ ] Cancellation propagates across all stages and releases KV/state, queue entries, and fragment buffers.
+- [ ] Duplicate steps are idempotent; uncertain mutations are never silently replayed.
+- [ ] Billing/work outcomes distinguish completed, cancelled, failed, and unverified work.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-058/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/059-implement-alpha-safe-route-recovery.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-059: Implement alpha-safe route recovery
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M4`
+- **Dependencies:** `DGR-043`, `DGR-058`
+- **Blocks (derived):** `DGR-070`
+- **Labels:** `area:recovery`, `area:routing`, `type:hardening`, `priority:p1`, `ready-for-agent`
+- **Evidence class:** `fixture`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/059-implement-alpha-safe-route-recovery.md`, and evidence READMEs for dependencies (DGR-043, DGR-058) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Recover from route loss without importing or continuing unverified state.
+
+## Acceptance criteria
+
+- [ ] On route loss or local-state cache miss, restart from token zero or re-prefill on a newly compatible route according to the locked alpha contract.
+- [ ] Never import KV, CSA, HCA, SWA, indexer, compressor, recurrent, or MTP cache/state across workers.
+- [ ] Keep exact same-route duplicate delivery idempotent while cross-route continuation fails closed.
+- [ ] Test direct/relay loss, cache miss, replacement selection, client cancellation, and billing reconciliation.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-059/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/06-implement-architecture-defined-boundary-input-output.md

@@ -1,61 +0,0 @@
-# 06 — Implement architecture-defined boundary input/output
-
-Status: done
-
-## Mandatory fresh-session context
-
-- Read [RALPH-CONTEXT.md](../RALPH-CONTEXT.md) completely before changing code.
-- This issue is `DGR-006` in [prd.json](../prd.json).
-- Read the evidence README for every dependency listed below.
-- Inspect current code and `git status`; historical text and previous agent claims are not evidence.
-
-## Description
-
-As a Shard, I need to consume and emit the correct transformer boundary state so that disjoint processes reproduce whole-model execution.
-
-## Expected durable outputs
-
-- Architecture boundary adapter
-- Whole-model/two-range parity tests and results
-- evidence/DGR-006/README.md
-
-## Acceptance criteria
-
-- [ ] Head accepts token IDs and owns token embedding.
-- [ ] Middle/tail bypass token embedding and accept the named boundary bundle.
-- [ ] Non-tail emits the unnormalized architecture-defined residual/boundary before final norm/head and before tail-only row pruning.
-- [ ] Tail emits logits or token output through an explicit sampling contract.
-- [ ] Dense-Llama whole-model versus two-range prefill and greedy-decode parity passes the documented tolerance.
-- [ ] The adapter interface fails closed for uncertified architectures.
-- [ ] 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-006/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
-
-## Dependency handoff
-
-- `DGR-002` must have `passes: true`; read `../evidence/DGR-002/README.md` and verify its referenced files/commands.
-- `DGR-005` must have `passes: true`; read `../evidence/DGR-005/README.md` and verify its referenced files/commands.
-
-## Finish contract
-
-- 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 `<promise>COMPLETE</promise>` only after the evidence handoff exists.
-
-## References
-
-- [Ralph execution context](../RALPH-CONTEXT.md)
-- [PRD](../PRD.md)
-- [Implementation strategy](../implementation-strategy.md)
-- [Current architecture](../architecture.md)
-- [Architecture decision](../../docs/adr/0024-distributed-gguf-runtime.md)

.scratch/distributed-gguf-runtime/issues/060-certify-v4-long-context-state-correctness.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-060: Certify V4 long-context state correctness
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M4`
+- **Dependencies:** `DGR-051`, `DGR-056`, `DGR-058`
+- **Blocks (derived):** `DGR-062`, `DGR-064`, `DGR-065`, `DGR-066`, `DGR-070`
+- **Labels:** `area:deepseek-v4`, `area:long-context`, `type:certification`, `priority:p1`, `ready-for-agent`
+- **Evidence class:** `real-hardware`
+- **Hardware:** `required`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/060-certify-v4-long-context-state-correctness.md`, and evidence READMEs for dependencies (DGR-051, DGR-056, DGR-058) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Prove V4’s KV and auxiliary state remain correct and bounded at long contexts.
+
+## Acceptance criteria
+
+- [ ] Exercise pre-locked context lengths covering multiple prefill chunks and sustained decode.
+- [ ] Validate KV plus CSA/HCA/SWA/indexer/compressor state positions across every stage.
+- [ ] Measure memory growth, fragment sizes, TTFT, decode degradation, cancellation latency, and cleanup.
+- [ ] Cache mismatch, truncation, and context-limit behavior fail deterministically.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-060/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/061-certify-existing-routing-with-10-gguf-stage-candidates.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-061: Certify existing routing with 10+ GGUF stage candidates
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M4`
+- **Dependencies:** `DGR-043`, `DGR-057`, `DGR-058`
+- **Blocks (derived):** `DGR-062`, `DGR-063`
+- **Labels:** `area:tracker`, `area:scale`, `type:simulation`, `priority:p1`, `ready-for-agent`
+- **Evidence class:** `fixture`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/061-certify-existing-routing-with-10-gguf-stage-candidates.md`, and evidence READMEs for dependencies (DGR-043, DGR-057, DGR-058) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Certify that existing backend-agnostic routing consumes GGUF compatibility and measured-cost inputs for a 10+ candidate scenario without algorithm or policy redesign.
+
+## Acceptance criteria
+
+- [ ] Generate deterministic pools with 10+ compatible GGUF stage candidates plus slower, overloaded, unhealthy, and incompatible alternatives.
+- [ ] Run the existing routing implementation unchanged and verify complete coverage, compatibility, acyclicity, and use of measured inputs.
+- [ ] Regression-test that no stage count, quant, fixed split, architecture, or backend sequence is encoded in production routing policy.
+- [ ] Verify existing route recomputation reacts to measured load/failure while tracker, load-balancing, billing, relay, and provider semantics remain unchanged.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-061/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/062-certify-a-dynamic-real-10-stage-v4-scenario.md

@@ -0,0 +1,40 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-062: Certify a dynamic real 10+ stage V4 scenario
+
+- **Status / triage:** specification only; `ready-for-human`; `passes: false`
+- **Execution mode:** `HITL`
+- **Milestone:** `M4`
+- **Dependencies:** `DGR-053`, `DGR-060`, `DGR-061`
+- **Blocks (derived):** `DGR-067`, `DGR-070`
+- **Labels:** `area:deepseek-v4`, `area:scale`, `area:hardware`, `type:certification`, `priority:p1`, `gate:hitl`, `ready-for-human`
+- **Evidence class:** `real-hardware`
+- **Hardware:** `required`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/062-certify-a-dynamic-real-10-stage-v4-scenario.md`, and evidence READMEs for dependencies (DGR-053, DGR-060, DGR-061) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Demonstrate that a large real route can be dynamically selected and usefully execute V4.
+
+## Acceptance criteria
+
+- [ ] Run one real 10+-stage V4 certification scenario; stage count, quant, and split remain scenario metadata only.
+- [ ] Every selected stage proves real work, exact compatible identity, local state ownership, and bounded resources.
+- [ ] Record end-to-end and per-stage TTFT, prefill/decode, seam cost, queueing, memory, failures, and cleanup.
+- [ ] Inject at least one incompatible or degraded candidate and verify dynamic exclusion/reselection.
+- [ ] The scenario must meet its pre-locked usefulness threshold or remain failed evidence.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-062/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/063-profile-and-optimize-the-critical-seam.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-063: Profile and optimize the critical seam
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M4`
+- **Dependencies:** `DGR-057`, `DGR-061`
+- **Blocks (derived):** `DGR-064`
+- **Labels:** `area:performance`, `type:optimization`, `priority:p1`, `ready-for-agent`
+- **Evidence class:** `real-hardware`
+- **Hardware:** `required`
+- **Model:** `generic`
+- **Upstream:** `conditional`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/063-profile-and-optimize-the-critical-seam.md`, and evidence READMEs for dependencies (DGR-057, DGR-061) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Optimize only the measured dominant compute, serialization, copy, or transport bottleneck.
+
+## Acceptance criteria
+
+- [ ] Profile worker compute, tensor conversion, copies, protobuf framing, compression, relay/direct transport, queueing, and synchronization.
+- [ ] Select one dominant bottleneck from evidence and lock its before/after benchmark.
+- [ ] Implement one bounded optimization without weakening correctness or protocol identity.
+- [ ] Report whether the optimization changes TTFT, prefill, decode, throughput, or memory and preserve raw data.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-063/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/064-add-negotiated-activation-compression.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-064: Add negotiated activation compression
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M4`
+- **Dependencies:** `DGR-060`, `DGR-063`
+- **Blocks (derived):** `DGR-066`, `DGR-070`
+- **Labels:** `area:protocol`, `area:compression`, `type:optimization`, `priority:p1`, `ready-for-agent`
+- **Evidence class:** `real-hardware`
+- **Hardware:** `required`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/064-add-negotiated-activation-compression.md`, and evidence READMEs for dependencies (DGR-060, DGR-063) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Reduce V4 seam cost only when a certified compression recipe improves end-to-end performance acceptably.
+
+## Acceptance criteria
+
+- [ ] Negotiate compression through recipe identity; unnegotiated or mismatched compression fails closed.
+- [ ] Preserve names, shapes, semantic axes, token-ID sideband, and checksums.
+- [ ] Measure quality drift, encode/decode cost, bytes, TTFT, and throughput against uncompressed boundaries.
+- [ ] Compression remains dark unless it meets pre-locked quality and speed thresholds.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-064/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/065-define-v4-mtp-ownership-and-distributed-state-contract.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-065: Define V4 MTP ownership and distributed state contract
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M4`
+- **Dependencies:** `DGR-051`, `DGR-054`, `DGR-060`
+- **Blocks (derived):** `DGR-066`
+- **Labels:** `area:deepseek-v4`, `area:mtp`, `type:contract`, `priority:p1`, `ready-for-agent`
+- **Evidence class:** `fixture`
+- **Hardware:** `none`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/065-define-v4-mtp-ownership-and-distributed-state-contract.md`, and evidence READMEs for dependencies (DGR-051, DGR-054, DGR-060) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Lock MTP tensor, execution, boundary, acceptance/rejection, and session-state ownership before implementation while keeping MTP disabled for alpha.
+
+## Acceptance criteria
+
+- [ ] Derive exact MTP tensor and execution ownership from the pinned V4 target and upstream llama.cpp graph, distinguishing main-layer, tail, and MTP responsibilities.
+- [ ] Define typed MTP inputs/outputs plus accepted-token, rejection, rollback/truncation, position, cache, and session/epoch lifecycle semantics.
+- [ ] Specify which MTP state remains shard-local and which typed boundary values cross a seam; prohibit WAN migration of KV or V4 auxiliary caches.
+- [ ] Keep every MTP recipe disabled and unroutable for alpha, with fail-closed capability negotiation and deterministic contract fixtures.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-065/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.