docs: target GLM-5.2 Max for distributed alpha

This commit is contained in:
Dobromir Popov
2026-07-13 22:32:14 +03:00
parent ef2a9e67e8
commit 5ebce15d7a
16 changed files with 866 additions and 65 deletions

View File

@@ -1,7 +1,7 @@
{
"name": "Performant Concurrent Distributed GGUF Runtime",
"branchName": "ralph/performant-concurrent-distributed-gguf",
"description": "Benchmark-gated native llama.cpp/GGUF Shards with gRPC streaming, concurrent local KV, continuous batching, real heterogeneous acceptance, and a measured release gate against Transformers/safetensors.",
"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",
@@ -26,7 +26,7 @@
"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": 2,
"priority": 1,
"passes": true,
"notes": "Source issue: .scratch/distributed-gguf-runtime/issues/01-lock-the-safetensors-versus-gguf-performance-contract.md",
"dependsOn": []
@@ -53,7 +53,7 @@
"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": 1,
"priority": 2,
"passes": true,
"notes": "Source issue: .scratch/distributed-gguf-runtime/issues/02-adopt-the-versioned-grpc-shard-protocol.md",
"dependsOn": []
@@ -79,11 +79,12 @@
"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": 3,
"priority": 4,
"passes": false,
"notes": "Source issue: .scratch/distributed-gguf-runtime/issues/03-define-exact-artifact-and-runtime-recipe-identity.md",
"dependsOn": [
"DGR-002"
"DGR-002",
"DGR-017"
]
},
{
@@ -110,11 +111,12 @@
"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": 4,
"priority": 5,
"passes": false,
"notes": "Source issue: .scratch/distributed-gguf-runtime/issues/04-create-the-reproducible-pinned-llama-cpp-patch-stack.md",
"dependsOn": [
"DGR-001"
"DGR-001",
"DGR-017"
]
},
{
@@ -140,7 +142,7 @@
"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": 5,
"priority": 6,
"passes": false,
"notes": "Source issue: .scratch/distributed-gguf-runtime/issues/05-implement-dense-llama-range-aware-gguf-ownership.md",
"dependsOn": [
@@ -172,7 +174,7 @@
"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": 6,
"priority": 7,
"passes": false,
"notes": "Source issue: .scratch/distributed-gguf-runtime/issues/06-implement-architecture-defined-boundary-input-output.md",
"dependsOn": [
@@ -204,11 +206,12 @@
"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": 7,
"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-006",
"DGR-019"
]
},
{
@@ -235,7 +238,7 @@
"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": 8,
"priority": 11,
"passes": false,
"notes": "Source issue: .scratch/distributed-gguf-runtime/issues/08-build-the-standalone-c-grpc-shard-worker.md",
"dependsOn": [
@@ -270,7 +273,7 @@
"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": 9,
"priority": 12,
"passes": false,
"notes": "Source issue: .scratch/distributed-gguf-runtime/issues/09-integrate-the-native-worker-with-meshnet.md",
"dependsOn": [
@@ -304,7 +307,7 @@
"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": 10,
"priority": 13,
"passes": false,
"notes": "Source issue: .scratch/distributed-gguf-runtime/issues/10-pass-local-real-model-two-process-acceptance.md",
"dependsOn": [
@@ -337,7 +340,7 @@
"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": 11,
"priority": 14,
"passes": false,
"notes": "Source issue: .scratch/distributed-gguf-runtime/issues/11-pass-a-real-heterogeneous-two-machine-route.md",
"dependsOn": [
@@ -368,7 +371,7 @@
"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": 12,
"priority": 17,
"passes": false,
"notes": "Source issue: .scratch/distributed-gguf-runtime/issues/12-implement-continuous-batching-and-bounded-admission.md",
"dependsOn": [
@@ -401,13 +404,12 @@
"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": 13,
"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",
"DGR-012"
"DGR-009"
]
},
{
@@ -435,7 +437,7 @@
"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": 14,
"priority": 18,
"passes": false,
"notes": "Source issue: .scratch/distributed-gguf-runtime/issues/14-enforce-the-gguf-versus-safetensors-release-gate.md",
"dependsOn": [
@@ -470,7 +472,7 @@
"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": 15,
"priority": 20,
"passes": false,
"notes": "Source issue: .scratch/distributed-gguf-runtime/issues/15-add-and-certify-a-qwen3-qwen3-moe-adapter.md",
"dependsOn": [
@@ -500,12 +502,147 @@
"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": 16,
"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, configurable per-node reserve, KV dtype/context, scratch reserve, and endpoint/tensor imbalance.",
"Count unified system RAM/integrated-GPU memory once and reject additive RAM+VRAM claims for one shared pool.",
"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": false,
"notes": "Source issue: .scratch/distributed-gguf-runtime/issues/17-lock-glm-5-2-max-target-and-alpha-contract.md",
"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 at least 224 GiB usable memory and approximately 250 GB free mounted storage; abort before download if storage would resolve under `/home` or requirements are unmet.",
"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",
"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",
"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 with at least 224 GiB aggregate usable admitted memory; no participating node may individually admit the complete recipe and unified memory is counted once.",
"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; 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",
"dependsOn": [
"DGR-007",
"DGR-008",
"DGR-009",
"DGR-011",
"DGR-013",
"DGR-017",
"DGR-018",
"DGR-019"
]
}
]
}