neuron-tai/.scratch/distributed-gguf-runtime/prd.json

{
  "name": "Performant Concurrent Distributed GGUF Runtime",
  "branchName": "ralph/performant-concurrent-distributed-gguf",
  "description": "Build a performant concurrent distributed GGUF runtime on Meshnet. Alpha is gated by exact GLM-5.2 UD-IQ1_S execution in reasoning_effort=max mode across consumer machines; synthetic or dense-fallback evidence cannot satisfy the target.",
  "userStories": [
    {
      "id": "DGR-001",
      "title": "Lock the safetensors-versus-GGUF performance contract",
      "description": "MANDATORY FRESH-SESSION CONTEXT: Read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md` and `.scratch/distributed-gguf-runtime/issues/01-lock-the-safetensors-versus-gguf-performance-contract.md` completely before coding. Read the evidence handoff for every dependency. The global goal is performant concurrent inference for models larger than one consumer node, using Meshnet as the sole control plane, gRPC/Protobuf as the Shard protocol, and a small pinned llama.cpp worker—not a stitched collection of runtimes.\n\nAs a runtime engineer, I need a controlled baseline so that GGUF work proceeds from measured speed, memory, and quality rather than reputation.",
      "acceptanceCriteria": [
        "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"
      ],
      "priority": 1,
      "passes": true,
      "notes": "Source issue: docs/issues/distributed-gguf-runtime/01-lock-the-safetensors-versus-gguf-performance-contract.md (moved on close, MAINT-003)",
      "dependsOn": []
    },
    {
      "id": "DGR-002",
      "title": "Adopt the versioned gRPC Shard protocol",
      "description": "MANDATORY FRESH-SESSION CONTEXT: Read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md` and `.scratch/distributed-gguf-runtime/issues/02-adopt-the-versioned-grpc-shard-protocol.md` completely before coding. Read the evidence handoff for every dependency. The global goal is performant concurrent inference for models larger than one consumer node, using Meshnet as the sole control plane, gRPC/Protobuf as the Shard protocol, and a small pinned llama.cpp worker—not a stitched collection of runtimes.\n\nAs a node developer, I need a battle-proven streaming protocol so that Python and C++ Shards communicate without a custom socket protocol.",
      "acceptanceCriteria": [
        "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++.",
        "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-002/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"
      ],
      "priority": 2,
      "passes": true,
      "notes": "Source issue: docs/issues/distributed-gguf-runtime/02-adopt-the-versioned-grpc-shard-protocol.md (moved on close, MAINT-003)",
      "dependsOn": []
    },
    {
      "id": "DGR-003",
      "title": "Define exact Artifact and runtime recipe identity",
      "description": "MANDATORY FRESH-SESSION CONTEXT: Read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md` and `.scratch/distributed-gguf-runtime/issues/03-define-exact-artifact-and-runtime-recipe-identity.md` completely before coding. Read the evidence handoff for every dependency. The global goal is performant concurrent inference for models larger than one consumer node, using Meshnet as the sole control plane, gRPC/Protobuf as the Shard protocol, and a small pinned llama.cpp worker—not a stitched collection of runtimes.\n\nAs the Tracker, I need exact compatibility identity so that only numerically and operationally compatible Shards form an Inference Route.",
      "acceptanceCriteria": [
        "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"
      ],
      "priority": 4,
      "passes": true,
      "notes": "DGR-003-emission: native loaded-artifact adapter derives exact identity from immutable GGUF/runtime inputs, doctor emits it only for that adapter, and SessionOpen fails closed before acceptance. Exact identities remain tracker-uncertified and dark until a real distributed forward is certified. (moved on close, MAINT-003)",
      "dependsOn": [
        "DGR-002",
        "DGR-017"
      ]
    },
    {
      "id": "DGR-004",
      "title": "Create the reproducible pinned llama.cpp patch stack",
      "description": "MANDATORY FRESH-SESSION CONTEXT: Read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md` and `.scratch/distributed-gguf-runtime/issues/04-create-the-reproducible-pinned-llama-cpp-patch-stack.md` completely before coding. Read the evidence handoff for every dependency. The global goal is performant concurrent inference for models larger than one consumer node, using Meshnet as the sole control plane, gRPC/Protobuf as the Shard protocol, and a small pinned llama.cpp worker—not a stitched collection of runtimes.\n\nAs a maintainer, I need a small auditable fork boundary so that upstream updates do not turn the runtime into an unmaintainable stitched codebase.",
      "acceptanceCriteria": [
        "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"
      ],
      "priority": 5,
      "passes": true,
      "notes": "Source issue: docs/issues/distributed-gguf-runtime/04-create-the-reproducible-pinned-llama-cpp-patch-stack.md (moved on close, MAINT-003)",
      "dependsOn": [
        "DGR-001",
        "DGR-017"
      ]
    },
    {
      "id": "DGR-005",
      "title": "Implement dense-Llama range-aware GGUF ownership",
      "description": "MANDATORY FRESH-SESSION CONTEXT: Read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md` and `.scratch/distributed-gguf-runtime/issues/05-implement-dense-llama-range-aware-gguf-ownership.md` completely before coding. Read the evidence handoff for every dependency. The global goal is performant concurrent inference for models larger than one consumer node, using Meshnet as the sole control plane, gRPC/Protobuf as the Shard protocol, and a small pinned llama.cpp worker—not a stitched collection of runtimes.\n\nAs 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.",
      "acceptanceCriteria": [
        "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"
      ],
      "priority": 6,
      "passes": true,
      "notes": "Source issue: docs/issues/distributed-gguf-runtime/05-implement-dense-llama-range-aware-gguf-ownership.md (moved on close, MAINT-003)",
      "dependsOn": [
        "DGR-003",
        "DGR-004"
      ]
    },
    {
      "id": "DGR-006",
      "title": "Implement architecture-defined boundary input/output",
      "description": "MANDATORY FRESH-SESSION CONTEXT: Read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md` and `.scratch/distributed-gguf-runtime/issues/06-implement-architecture-defined-boundary-input-output.md` completely before coding. Read the evidence handoff for every dependency. The global goal is performant concurrent inference for models larger than one consumer node, using Meshnet as the sole control plane, gRPC/Protobuf as the Shard protocol, and a small pinned llama.cpp worker—not a stitched collection of runtimes.\n\nAs a Shard, I need to consume and emit the correct transformer boundary state so that disjoint processes reproduce whole-model execution.",
      "acceptanceCriteria": [
        "Head accepts token IDs and owns token embedding.",
        "Middle/tail bypass token embedding and accept the named boundary bundle.",
        "Amend the decode fast path so `DecodeStep` carries a versioned `TensorBundle`, not one `NamedTensor`; retain a compact one-tensor encoding and fallback compatibility, regenerate Python/C++ schema code, and update protocol goldens.",
        "Define an explicit typed tail result for logits and/or sampled token output, with sampling parameters and chat-template/reasoning mode bound to exact request/recipe identity.",
        "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"
      ],
      "priority": 7,
      "passes": true,
      "notes": "Source issue: docs/issues/distributed-gguf-runtime/06-implement-architecture-defined-boundary-input-output.md (moved on close, MAINT-003)",
      "dependsOn": [
        "DGR-002",
        "DGR-005"
      ]
    },
    {
      "id": "DGR-007",
      "title": "Add isolated concurrent local Hot KV State",
      "description": "MANDATORY FRESH-SESSION CONTEXT: Read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md` and `.scratch/distributed-gguf-runtime/issues/07-add-isolated-concurrent-local-hot-kv-state.md` completely before coding. Read the evidence handoff for every dependency. The global goal is performant concurrent inference for models larger than one consumer node, using Meshnet as the sole control plane, gRPC/Protobuf as the Shard protocol, and a small pinned llama.cpp worker—not a stitched collection of runtimes.\n\nAs a client, I need concurrent Route Sessions to retain independent per-Shard cache so that one request cannot clear or corrupt another.",
      "acceptanceCriteria": [
        "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.",
        "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-007/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"
      ],
      "priority": 10,
      "passes": false,
      "notes": "Source issue: .scratch/distributed-gguf-runtime/issues/07-add-isolated-concurrent-local-hot-kv-state.md",
      "dependsOn": [
        "DGR-006",
        "DGR-019"
      ]
    },
    {
      "id": "DGR-008",
      "title": "Build the standalone C++ gRPC Shard worker",
      "description": "MANDATORY FRESH-SESSION CONTEXT: Read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md` and `.scratch/distributed-gguf-runtime/issues/08-build-the-standalone-c-grpc-shard-worker.md` completely before coding. Read the evidence handoff for every dependency. The global goal is performant concurrent inference for models larger than one consumer node, using Meshnet as the sole control plane, gRPC/Protobuf as the Shard protocol, and a small pinned llama.cpp worker—not a stitched collection of runtimes.\n\nAs a node runtime, I need one supervised native process so that llama.cpp internals remain behind a stable project-owned protocol.",
      "acceptanceCriteria": [
        "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.",
        "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-008/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"
      ],
      "priority": 11,
      "passes": false,
      "notes": "Source issue: .scratch/distributed-gguf-runtime/issues/08-build-the-standalone-c-grpc-shard-worker.md",
      "dependsOn": [
        "DGR-002",
        "DGR-003",
        "DGR-004",
        "DGR-006",
        "DGR-007"
      ]
    },
    {
      "id": "DGR-009",
      "title": "Integrate the native worker with Meshnet",
      "description": "MANDATORY FRESH-SESSION CONTEXT: Read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md` and `.scratch/distributed-gguf-runtime/issues/09-integrate-the-native-worker-with-meshnet.md` completely before coding. Read the evidence handoff for every dependency. The global goal is performant concurrent inference for models larger than one consumer node, using Meshnet as the sole control plane, gRPC/Protobuf as the Shard protocol, and a small pinned llama.cpp worker—not a stitched collection of runtimes.\n\nAs 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.",
      "acceptanceCriteria": [
        "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.",
        "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-009/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"
      ],
      "priority": 12,
      "passes": false,
      "notes": "Source issue: .scratch/distributed-gguf-runtime/issues/09-integrate-the-native-worker-with-meshnet.md",
      "dependsOn": [
        "DGR-003",
        "DGR-008"
      ]
    },
    {
      "id": "DGR-010",
      "title": "Pass local real-model two-process acceptance",
      "description": "MANDATORY FRESH-SESSION CONTEXT: Read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md` and `.scratch/distributed-gguf-runtime/issues/10-pass-local-real-model-two-process-acceptance.md` completely before coding. Read the evidence handoff for every dependency. The global goal is performant concurrent inference for models larger than one consumer node, using Meshnet as the sole control plane, gRPC/Protobuf as the Shard protocol, and a small pinned llama.cpp worker—not a stitched collection of runtimes.\n\nAs a release engineer, I need real local distributed parity before involving network variability.",
      "acceptanceCriteria": [
        "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.",
        "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",
        "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-010/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"
      ],
      "priority": 13,
      "passes": false,
      "notes": "Source issue: .scratch/distributed-gguf-runtime/issues/10-pass-local-real-model-two-process-acceptance.md",
      "dependsOn": [
        "DGR-009"
      ]
    },
    {
      "id": "DGR-011",
      "title": "Pass a real heterogeneous two-machine route",
      "description": "MANDATORY FRESH-SESSION CONTEXT: Read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md` and `.scratch/distributed-gguf-runtime/issues/11-pass-a-real-heterogeneous-two-machine-route.md` completely before coding. Read the evidence handoff for every dependency. The global goal is performant concurrent inference for models larger than one consumer node, using Meshnet as the sole control plane, gRPC/Protobuf as the Shard protocol, and a small pinned llama.cpp worker—not a stitched collection of runtimes.\n\nAs a consumer-hardware operator, I need two physical machines to execute one GGUF model so that the distributed claim is real.",
      "acceptanceCriteria": [
        "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.",
        "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",
        "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-011/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"
      ],
      "priority": 14,
      "passes": false,
      "notes": "Source issue: .scratch/distributed-gguf-runtime/issues/11-pass-a-real-heterogeneous-two-machine-route.md",
      "dependsOn": [
        "DGR-010"
      ]
    },
    {
      "id": "DGR-012",
      "title": "Implement continuous batching and bounded admission",
      "description": "MANDATORY FRESH-SESSION CONTEXT: Read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md` and `.scratch/distributed-gguf-runtime/issues/12-implement-continuous-batching-and-bounded-admission.md` completely before coding. Read the evidence handoff for every dependency. The global goal is performant concurrent inference for models larger than one consumer node, using Meshnet as the sole control plane, gRPC/Protobuf as the Shard protocol, and a small pinned llama.cpp worker—not a stitched collection of runtimes.\n\nAs a node operator, I need active sessions batched safely so that concurrency increases aggregate throughput rather than serializing every request.",
      "acceptanceCriteria": [
        "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.",
        "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-012/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"
      ],
      "priority": 17,
      "passes": false,
      "notes": "Source issue: .scratch/distributed-gguf-runtime/issues/12-implement-continuous-batching-and-bounded-admission.md",
      "dependsOn": [
        "DGR-007",
        "DGR-009",
        "DGR-010"
      ]
    },
    {
      "id": "DGR-013",
      "title": "Harden failure, cancellation, and restart semantics",
      "description": "MANDATORY FRESH-SESSION CONTEXT: Read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md` and `.scratch/distributed-gguf-runtime/issues/13-harden-failure-cancellation-and-restart-semantics.md` completely before coding. Read the evidence handoff for every dependency. The global goal is performant concurrent inference for models larger than one consumer node, using Meshnet as the sole control plane, gRPC/Protobuf as the Shard protocol, and a small pinned llama.cpp worker—not a stitched collection of runtimes.\n\nAs a client, I need failures to be bounded and explicit so that distributed speed does not come with hanging or corrupted generations.",
      "acceptanceCriteria": [
        "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.",
        "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-013/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"
      ],
      "priority": 15,
      "passes": false,
      "notes": "Source issue: .scratch/distributed-gguf-runtime/issues/13-harden-failure-cancellation-and-restart-semantics.md",
      "dependsOn": [
        "DGR-008",
        "DGR-009"
      ]
    },
    {
      "id": "DGR-014",
      "title": "Enforce the GGUF-versus-safetensors release gate",
      "description": "MANDATORY FRESH-SESSION CONTEXT: Read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md` and `.scratch/distributed-gguf-runtime/issues/14-enforce-the-gguf-versus-safetensors-release-gate.md` completely before coding. Read the evidence handoff for every dependency. The global goal is performant concurrent inference for models larger than one consumer node, using Meshnet as the sole control plane, gRPC/Protobuf as the Shard protocol, and a small pinned llama.cpp worker—not a stitched collection of runtimes.\n\nAs the product owner, I need an end-to-end comparison so that the native runtime ships only if it advances model access or performance.",
      "acceptanceCriteria": [
        "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.",
        "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",
        "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-014/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"
      ],
      "priority": 18,
      "passes": false,
      "notes": "Source issue: .scratch/distributed-gguf-runtime/issues/14-enforce-the-gguf-versus-safetensors-release-gate.md",
      "dependsOn": [
        "DGR-001",
        "DGR-011",
        "DGR-012",
        "DGR-013"
      ]
    },
    {
      "id": "DGR-015",
      "title": "Add and certify a Qwen3/Qwen3-MoE adapter",
      "description": "MANDATORY FRESH-SESSION CONTEXT: Read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md` and `.scratch/distributed-gguf-runtime/issues/15-add-and-certify-a-qwen3-qwen3-moe-adapter.md` completely before coding. Read the evidence handoff for every dependency. The global goal is performant concurrent inference for models larger than one consumer node, using Meshnet as the sole control plane, gRPC/Protobuf as the Shard protocol, and a small pinned llama.cpp worker—not a stitched collection of runtimes.\n\nAs a client seeking top models, I need a separately certified MoE-capable architecture after the dense runtime proves stable.",
      "acceptanceCriteria": [
        "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.",
        "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",
        "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-015/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"
      ],
      "priority": 20,
      "passes": false,
      "notes": "Source issue: .scratch/distributed-gguf-runtime/issues/15-add-and-certify-a-qwen3-qwen3-moe-adapter.md",
      "dependsOn": [
        "DGR-014"
      ]
    },
    {
      "id": "DGR-016",
      "title": "Produce the upstream llama.cpp collaboration package",
      "description": "MANDATORY FRESH-SESSION CONTEXT: Read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md` and `.scratch/distributed-gguf-runtime/issues/16-produce-the-upstream-llama-cpp-collaboration-package.md` completely before coding. Read the evidence handoff for every dependency. The global goal is performant concurrent inference for models larger than one consumer node, using Meshnet as the sole control plane, gRPC/Protobuf as the Shard protocol, and a small pinned llama.cpp worker—not a stitched collection of runtimes.\n\nAs a maintainer, I need narrow upstreamable proposals so that our patch burden can shrink without asking llama.cpp to own Meshnet networking.",
      "acceptanceCriteria": [
        "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.",
        "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-016/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"
      ],
      "priority": 19,
      "passes": false,
      "notes": "Source issue: .scratch/distributed-gguf-runtime/issues/16-produce-the-upstream-llama-cpp-collaboration-package.md",
      "dependsOn": [
        "DGR-010"
      ]
    },
    {
      "id": "DGR-017",
      "title": "Lock the GLM-5.2 Max target and alpha contract",
      "description": "MANDATORY FRESH-SESSION CONTEXT: Read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, `.scratch/distributed-gguf-runtime/GLM-5.2-MAX-ALPHA-ROADMAP.md`, and `.scratch/distributed-gguf-runtime/issues/17-lock-glm-5-2-max-target-and-alpha-contract.md` completely before coding. Read and verify every dependency evidence README.\n\nAs a release owner, I need one exact GLM-5.2 Max target and immutable alpha contract so that later agents cannot swap artifacts, runtime semantics, hardware accounting, or thresholds after seeing results.",
      "acceptanceCriteria": [
        "Pin `zai-org/GLM-5.2` and `unsloth/GLM-5.2-GGUF` by exact observed repository revisions and identify `UD-IQ1_S` as the alpha quantization.",
        "Resolve all six `UD-IQ1_S` filenames, exact byte sizes, LFS SHA-256 values, aggregate decimal GB/GiB, license, and source URLs without downloading the weight payloads.",
        "Snapshot and hash architecture-critical config/tokenizer/chat-template metadata, including main/NextN layer counts, hidden width, experts/top-k, DSA top-k, IndexShare roles, context maximum, and `reasoning_effort=max` behavior.",
        "Generate deterministic minimum-node calculations from exact artifact bytes, Q8_0 MLA/indexer KV at 16K context/concurrency 1, endpoint/tensor imbalance, and a per-node reserve of at least `max(20% of physically usable memory, 8 GiB)`.",
        "Classify 224 GiB aggregate runtime-accessible memory as an experimental hard-fit floor, not a conservative envelope; recommend 5×64 GiB or 3×96/128 GiB unless exact measured placement proves an arithmetic-minimum topology.",
        "Count unified system RAM/integrated-GPU memory once and reject additive RAM+VRAM claims for one shared pool.",
        "Lock same-switch wired 2.5 GbE as the alpha minimum and 10 GbE as recommended; model serial seam latency separately from bandwidth.",
        "Lock the identity, semantic correctness, target-run, performance, reliability, and mounted-storage criteria from the roadmap in a machine-readable contract before full target execution.",
        "Refresh and record current upstream llama.cpp GLM-5.2/DSA/IndexShare/MTP support and focused donor candidates; do not adopt a broad donor fork or scheduler.",
        "Add tests that reject changed revisions, missing shards, inconsistent aggregate bytes, duplicate unified-memory accounting, and post-result threshold mutation.",
        "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 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 `evidence/DGR-017/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."
      ],
      "priority": 3,
      "passes": true,
      "notes": "Source issue: docs/issues/distributed-gguf-runtime/17-lock-glm-5-2-max-target-and-alpha-contract.md (moved on close, MAINT-003)",
      "dependsOn": [
        "DGR-001",
        "DGR-002"
      ]
    },
    {
      "id": "DGR-018",
      "title": "Certify whole-model GLM-5.2 runtime semantics",
      "description": "MANDATORY FRESH-SESSION CONTEXT: Read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, `.scratch/distributed-gguf-runtime/GLM-5.2-MAX-ALPHA-ROADMAP.md`, and `.scratch/distributed-gguf-runtime/issues/18-certify-whole-model-glm-5-2-runtime-semantics.md` completely before coding. Read and verify every dependency evidence README.\n\nAs a runtime maintainer, I need a certified whole-model oracle for the exact lowest-quant GLM-5.2 artifact so that distributed parity is measured against correct MoE, DSA, IndexShare, cache, and Max-template semantics.",
      "acceptanceCriteria": [
        "Preflight a 256-GiB-class reference host with at least 224 GiB runtime-accessible memory after OS reservation and approximately 250 GB free mounted storage; abort before download if storage resolves under `/home` or requirements are unmet.",
        "Configure the oracle's alpha lane for 16,384 context, concurrency 1, and Q8_0 MLA/indexer KV; record actual MLA, indexer-cache, scratch, and peak resident allocations separately.",
        "Download/resume and verify all six DGR-017 `UD-IQ1_S` files against exact sizes and LFS SHA-256 values.",
        "Load the target with the unmodified DGR-004 pin first and retain full logs, tensor warnings, peak memory, context/KV allocation, TTFT, and decode timing.",
        "Prove from graph/runtime evidence whether 256-expert MoE/top-8/shared expert, DSA lightning indexer/sparse attention, IndexShare Full/Shared reuse, and `reasoning_effort=max` are active.",
        "Dense-attention or replicated-indexer compatibility fallback is labeled incomplete and cannot become the oracle solely because it emits plausible text.",
        "Audit focused upstream/Mesh-LLM donor tests and patches; adopt or rewrite only independently understood minimum changes and record provenance/rejection rationale.",
        "Handle the trailing NextN/MTP tensors explicitly; MTP may remain disabled for alpha, but ignored tensors and layer-count behavior must be understood and tested.",
        "Run deterministic prefill/greedy decode and fixed Max-mode coding, structured-output/tool-call, and reasoning sentinels; retain raw prompts, outputs, token IDs, and compared state/logit evidence.",
        "Bind the oracle to exact artifact, tokenizer/template, adapter, backend class, compute/activation/KV dtypes, context/RoPE, llama.cpp commit, and patch-series hash.",
        "Produce a signed `pass` or `stop` semantic-runtime verdict; no performance threshold is weakened after execution.",
        "Targeted native/unit tests and clean pinned rebuild pass.",
        "`git diff --check` passes.",
        "Default tests remain model-download-free/GPU-free; full-target execution is opt-in and never runs in default CI.",
        "Model artifacts and caches remain on configured mounted-drive storage and never under `/home`.",
        "Preserve all pre-existing working-tree changes and stage only files belonging to this story.",
        "Write `evidence/DGR-018/README.md` with exact hardware, storage, source revisions, files, commands, raw-result paths, real results, limitations, and handoff.",
        "Update only this story issue to `Status: done` after every acceptance criterion passes."
      ],
      "priority": 8,
      "passes": false,
      "notes": "Source issue: .scratch/distributed-gguf-runtime/issues/18-certify-whole-model-glm-5-2-runtime-semantics.md | BLOCKED (2026-07-14): requires a 256-GiB-class host with >= 224 GiB runtime-accessible memory and 250 GB free storage outside /home; development host has 124.9 GiB MemTotal and no eligible filesystem. Exact preflight output: evidence/DGR-018/BLOCKED.md. Preflight scripts preserved at commit a0f28b5.",
      "dependsOn": [
        "DGR-003",
        "DGR-004",
        "DGR-017"
      ]
    },
    {
      "id": "DGR-019",
      "title": "Implement and certify GLM-5.2 range, DSA, and IndexShare semantics",
      "description": "MANDATORY FRESH-SESSION CONTEXT: Read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, `.scratch/distributed-gguf-runtime/GLM-5.2-MAX-ALPHA-ROADMAP.md`, and `.scratch/distributed-gguf-runtime/issues/19-implement-and-certify-glm-5-2-range-dsa-indexshare.md` completely before coding. Read and verify every dependency evidence README.\n\nAs a target-model operator, I need explicit range-owned GLM-5.2 semantics so that contiguous consumer Shards preserve the whole-model MoE, DSA, IndexShare, and local-KV computation.",
      "acceptanceCriteria": [
        "Implement explicit ownership for 78 main layers, head embedding, tail norm/output head, routed/shared experts, DSA/indexer tensors, and the certified NextN/MTP policy.",
        "Each contiguous layer owner keeps all 256 experts and the shared-expert path for its layers local; no public cross-machine expert collectives are introduced.",
        "Define and fixture-test compressed MLA KV ownership for locally owned layers, keyed by Route Session/epoch, for DGR-007 to implement.",
        "Implement native DSA lightning indexer/top-2,048 and sparse-attention graph behavior matching DGR-018.",
        "Parse and validate artifact `indexer_types`; implement Full producer and Shared consumer behavior without fabricated/duplicated indexer tensors.",
        "Prefer Shard boundaries that preserve IndexShare ownership groups; when memory fit forces a split, carry a typed, bounded, validated top-k sideband in the DGR-006 named bundle.",
        "Reject missing, stale, wrong-width, wrong-position, or Shared-before-Full sideband/index state.",
        "Demonstrate mapped/resident weights and allocated KV scale with exact owned tensors/layers rather than the full model.",
        "Same-host two-stage F32 seam fixture produces 32 exact greedy tokens against the DGR-018 semantics; production seam meets the pre-locked token/similarity thresholds.",
        "If full-target same-host execution cannot fit, use a layer-reduced GLM architecture fixture only for graph parity and defer full-artifact parity to DGR-020; label it non-target evidence.",
        "Add deterministic fixture tests for MoE route/shared expert, DSA Full/Shared groups, internal group split, endpoint ownership, KV filtering, malformed metadata, and NextN policy.",
        "Targeted pytest/CTest/native tests pass; pinned patch stack applies and rebuilds cleanly.",
        "`python -m compileall packages tests` and `git diff --check` pass.",
        "Default tests remain deterministic, model-download-free, API-credit-free, and GPU-free.",
        "Full deterministic `pytest -q` passes, or exact pre-existing unrelated failures are recorded.",
        "Preserve all pre-existing working-tree changes and stage only files belonging to this story.",
        "Write `evidence/DGR-019/README.md` with files, commands, real results, raw evidence, limitations, and dependent-story handoff.",
        "Update only this story issue to `Status: done` after every acceptance criterion passes."
      ],
      "priority": 9,
      "passes": false,
      "notes": "Source issue: .scratch/distributed-gguf-runtime/issues/19-implement-and-certify-glm-5-2-range-dsa-indexshare.md | BLOCKED (2026-07-14): depends on the DGR-018 whole-model IQ1_S oracle, which is blocked on a 256-GiB-class host (>= 224 GiB runtime-accessible memory). See evidence/DGR-018/BLOCKED.md.",
      "dependsOn": [
        "DGR-005",
        "DGR-006",
        "DGR-018"
      ]
    },
    {
      "id": "DGR-020",
      "title": "Pass real distributed GLM-5.2 Max alpha acceptance",
      "description": "MANDATORY FRESH-SESSION CONTEXT: Read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, `.scratch/distributed-gguf-runtime/GLM-5.2-MAX-ALPHA-ROADMAP.md`, and `.scratch/distributed-gguf-runtime/issues/20-pass-real-distributed-glm-5-2-max-alpha.md` completely before coding. Read and verify every dependency evidence README.\n\nAs an alpha user, I need the exact lowest-quant GLM-5.2 model to run in Max reasoning mode across consumer machines through Meshnet so that the project has proven its end goal on real hardware.",
      "acceptanceCriteria": [
        "Use the exact DGR-017 `UD-IQ1_S` artifact and certified DGR-018/DGR-019 runtime recipe with all source and patch hashes verified.",
        "Use at least two physical consumer machines; each reserves at least `max(20% of physically usable memory, 8 GiB)` outside weight-plus-Q8-KV placement, no node can place the complete recipe, unified memory is counted once, and measured peak use stays within physical memory without swap/overcommit.",
        "Treat 5×64 GiB or 3×96/128 GiB as the recommended topology; arithmetic-minimum 4×64 or 2×128 qualifies only with exact contiguous placement and measured reserve evidence.",
        "Use a same-switch wired network with at least 2.5 GbE; record 10 GbE as recommended and measure hop RTT/serialization/queue latency.",
        "Tracker selects disjoint contiguous Shards whose exact required tensor inventory has complete union and no unintended overlap.",
        "Every stage reports real CPU/GPU compute, owned tensor bytes/layers, local KV, backend, queue, and seam telemetry; synthetic, passthrough, or zero-layer workers fail acceptance.",
        "Runtime evidence proves native GLM MoE/shared expert, DSA lightning indexer/sparse attention, and IndexShare Full/Shared paths are active; dense fallback fails acceptance.",
        "OpenAI-compatible API applies and records `reasoning_effort=max`, stable model ID, finish reason, and token usage.",
        "Configure 16,384 context, concurrency 1, and Q8_0 MLA/indexer KV; complete the fixed 4,096-token prefill lane and generate at least 512 output tokens or valid natural EOS after at least 128 tokens.",
        "Production seam meets at least 0.90 greedy token agreement and 0.999 mean compared-state/logit cosine similarity against DGR-018 on the fixed corpus, with no non-finite or malformed tensors.",
        "Fixed coding, structured tool-call/JSON, and multi-step reasoning sentinels produce parseable relevant outputs retained for human review.",
        "After warm-up, fixed Max lane median decode is at least 0.5 token/s, 4,096-token-prompt TTFT is at most 10 minutes, and no unexplained stall exceeds 60 seconds without progress telemetry.",
        "Record per-stage/seam p50/p95 latency, bytes, compute time, peak RSS/VRAM, KV pressure, network properties, errors, and total energy when available.",
        "Two consecutive cold starts load, generate, release, and exit without leaked processes, mapped weights, queues, or KV leases.",
        "Cancellation in prefill and decode releases all stages; one worker loss aborts the route; retry starts from token zero on a newly compatible route; stale epochs and duplicate steps fail closed.",
        "Model artifacts/caches remain on configured mounted-drive storage and never under `/home`; secret scan passes.",
        "Run targeted/full deterministic tests and clean native rebuild in addition to target execution; `git diff --check` passes.",
        "Preserve all raw failures and do not weaken DGR-017 thresholds after results.",
        "Write a signed `alpha` verdict only if every criterion passes; otherwise write `stop` with the measured bottleneck and next narrow action.",
        "Write `evidence/DGR-020/README.md` with exact commands, manifests, raw-result paths, outputs, limitations, and post-alpha handoff.",
        "Update only this story issue to `Status: done` after the immutable verdict and all evidence exist."
      ],
      "priority": 16,
      "passes": false,
      "notes": "Source issue: .scratch/distributed-gguf-runtime/issues/20-pass-real-distributed-glm-5-2-max-alpha.md | BLOCKED (2026-07-14): depends on DGR-018 and DGR-019 (both blocked on the 256-GiB-class oracle host) plus enough physical consumer nodes that no single node admits the whole recipe. See evidence/DGR-018/BLOCKED.md.",
      "dependsOn": [
        "DGR-007",
        "DGR-008",
        "DGR-009",
        "DGR-011",
        "DGR-013",
        "DGR-017",
        "DGR-018",
        "DGR-019"
      ]
    }
  ]
}