docs: harden GLM alpha resource and protocol gates

.scratch/distributed-gguf-runtime/GLM-5.2-MAX-ALPHA-ROADMAP.md

@@ -28,11 +28,13 @@ The shortest safe path is not “support every GGUF architecture.” Dense Llama
 |---|---|
 | Official repository | `zai-org/GLM-5.2` |
 | Official revision observed 2026-07-13 | `b4734de4facf877f85769a911abafc5283eab3d9` |
-| License | MIT |
+| Model-weight license | MIT |
+| Official code/documentation license | Apache-2.0 |
 | Architecture | `glm_moe_dsa` / `GlmMoeDsaForCausalLM` |
-| Total parameters | 744B |
+| Official architecture label | 744B total / approximately 40B active per token |
-| Active parameters | approximately 40B/token |
+| Exact stored checkpoint tensors | 753,329,940,480 parameters |
-| Transformer layers | 78 main layers plus one shared NextN/MTP layer in the artifact |
+| Transformer layers | 78 backbone layers plus one shared NextN/MTP layer in the artifact |
+| Layer types | first 3 dense; remaining 75 sparse MoE |
 | Routed experts | 256 |
 | Experts selected | 8 routed experts plus shared expert path |
 | Hidden width | 6,144 |
@@ -88,33 +90,39 @@ Not required for alpha:
 
 ### 2.1 Weight and runtime memory
 
-The smallest artifact occupies 201.832 GiB before KV, scratch buffers, backend workspaces, process memory, and the operating system. The alpha planner uses **224 GiB aggregate usable model memory** as the initial conservative admission floor and records actual peak memory. “Usable” means memory available after per-node OS/runtime reserve, not installed capacity.
+The smallest artifact occupies 201.832 GiB before KV, DSA indexer state, scratch buffers, backend workspaces, process memory, and the operating system. **224 GiB aggregate runtime-accessible memory is only the experimental hard-fit floor**, consistent with Unsloth's approximate 223 GB one-bit requirement. It is not a conservative operational envelope.
 
-Unified memory is counted once. An integrated GPU's reported VRAM must not be added again to the same physical system RAM.
+For admission, each node reserves:
 
-| Consumer-node class | Reserve per node | Usable per node | Minimum nodes for 224 GiB | Position |
+```text
+max(20% of physically usable memory, 8 GiB)
+```
+
+The remainder is the combined weight-plus-KV placement budget. Actual peak scratch is measured by backend/context and can force one extra node. Unified memory is counted once: integrated-GPU “VRAM” must not be added again to the same physical system RAM.
+
+| Physical usable tier | Minimum reserve | Weight + KV placement budget | IQ1_S 16K arithmetic minimum | Operational position |
 |---:|---:|---:|---:|---|
-| 32 GiB | 6 GiB | 26 GiB | 9 | technically possible; operationally poor |
+| 32 GiB | 8.0 GiB | 24.0 GiB | 9 nodes | use 10 if attempted; latency-heavy |
-| 48 GiB | 8 GiB | 40 GiB | 6 | possible |
+| 48 GiB | 9.6 GiB | 38.4 GiB | 6 nodes | possible; latency-heavy |
-| 64 GiB | 8 GiB | 56 GiB | 4 | minimum practical route |
+| 64 GiB | 12.8 GiB | 51.2 GiB | 4 nodes | hard minimum; **5 recommended** |
-| 96 GiB | 12 GiB | 84 GiB | 3 | preferred |
+| 96 GiB | 19.2 GiB | 76.8 GiB | 3 nodes | recommended |
-| 128 GiB unified/system | 16 GiB | 112 GiB | 2 | minimum high-memory route; narrow headroom |
+| 128 GiB unified/system | 25.6 GiB | 102.4 GiB | 2 nodes | arithmetic hard minimum; **3 recommended** |
 
-The planner must use exact tensor byte ownership, not equal percentages. Embeddings, final head, shared experts, indexer tensors, quant block alignment, and backend workspace can make equal layer counts unequal in memory.
+The planner must use exact tensor byte ownership, not equal percentages. Embeddings, final head, dense versus MoE layers, shared experts, indexer tensors, quant block alignment, KV distribution, and backend workspace make equal layer counts unequal in memory.
 
-Recommended first target route: **three 96/128-GiB-class physical machines** or **four 64-GiB-class machines**, each with at least 1 GbE and mounted model storage. Two 128-GiB machines are a valuable minimum-fit trial but not the only certification topology.
+Recommended first target route: **three 96/128-GiB-class physical machines** or **five 64-GiB-class machines**, on the same wired switch with mounted model storage. Four 64-GiB or two 128-GiB machines are fit probes only and qualify solely if exact placement and measured peak-memory evidence retain the required reserve with no swap/overcommit.
 
 ### 2.2 KV cache
 
-GLM-5.2 MLA stores approximately 576 latent/rope elements per token per main layer. Across 78 layers:
+GLM-5.2 MLA caches 576 latent/rope values per token per backbone layer. Correct DSA also caches 128-dimensional indexer keys: ideally only for the 21 Full indexer layers, while the current experimental implementation may allocate them across all 78 layers. Alpha locks **Q8_0 KV** for quality and budgets the conservative current-implementation layout.
 
-| Context | F16 KV, aggregate | Approx. Q4_1 KV, aggregate |
+| Context × concurrency | MLA-only Q8 | Optimized DSA Q8 | Conservative current-DSA Q8 | Conservative current-DSA F16 |
-|---:|---:|---:|
+|---:|---:|---:|---:|---:|
-| 16,384 | 1.37 GiB | 0.43 GiB |
+| 16,384 × 1 | 0.73 GiB | 0.77 GiB | **0.89 GiB** | 1.68 GiB |
-| 131,072 | 10.97 GiB | 3.43 GiB |
+| 131,072 × 1 | 5.83 GiB | 6.18 GiB | **7.12 GiB** | 13.41 GiB |
-| 1,048,576 | 87.75 GiB | 27.42 GiB |
+| 1,048,576 × 1 | 46.62 GiB | 49.41 GiB | **56.98 GiB** | 107.25 GiB |
 
-These are planning estimates, not admission truth. The runtime must report measured allocated/resident KV by Shard and recipe. Alpha configures a 16,384-token window, uses one session, and records the exact KV dtype. Longer contexts are later certification gates.
+These are planning estimates, not admission truth. The runtime must report measured allocated/resident MLA and indexer cache by Shard. Alpha configures a 16,384-token window, Q8_0 KV, and one session. Longer contexts and lower-bit KV are separate quality/resource certification gates.
 
 ### 2.3 Activation seams and network
 
@@ -127,7 +135,7 @@ A BF16 hidden-state boundary is 6,144 elements = 12,288 bytes/token before frami
 
 If a Shard boundary splits an IndexShare producer/consumer group, a 2,048-entry int32 top-k sideband can add up to 8 KiB/query before framing. The route planner should prefer boundaries that preserve complete IndexShare ownership groups. The protocol must still support and validate the named sideband because memory fit may force an internal group split.
 
-Bandwidth is manageable on 1 GbE; sequential seam latency and compute dominate decode. Alpha records per-seam bytes, p50/p95 transfer latency, retries, and checksum failures. No speed claim is inferred from link speed alone.
+Decode bandwidth is small, but every generated token crosses all seams serially, so node count and per-hop latency dominate. Alpha requires a same-switch wired route: **2.5 GbE minimum and 10 GbE recommended**, with measured one-way/RTT, serialization, and queue latency. A 1 GbE route may be retained as fit-only evidence but is not the recommended alpha topology. Alpha records per-seam bytes, p50/p95 transfer latency, retries, and checksum failures; no speed claim is inferred from link rate alone.
 
 ### 2.4 Storage
 
@@ -153,12 +161,13 @@ Deterministic source-bound layer packages are a follow-up optimization. If neede
 
 1. Exact GLM target/artifact manifest and memory-fit planner.
 2. A current llama.cpp pin proven to load and generate with the exact `UD-IQ1_S` artifact.
-3. A narrow decision on native GLM-5.2 DSA/IndexShare support. As observed 2026-07-13, llama.cpp issue #24730 remains open and community GGUF execution may use incomplete or compatibility paths.
+3. A narrow decision on native GLM-5.2 DSA/IndexShare support. As observed 2026-07-13, merged llama.cpp PR #24770 loads GLM-5.2 through a dense-MLA compatibility path, while full IndexShare/DSA PR #25407 remains open and its generic sparse path can be slower than dense fallback. Generic CPU lightning-indexer support is merged; backend coverage remains uneven.
-4. Correct range-owned GGUF loading and memory proof.
+4. A decode protocol amendment. `ActivationChunk` carries `TensorBundle`, but the current `DecodeStep` fast path carries only one `NamedTensor`; it cannot transport a hidden state plus GLM top-k sideband. Tail token/logit and sampling behavior also needs an explicit typed result contract.
-5. GLM-specific boundary/KV/IndexShare semantics.
+5. Correct range-owned GGUF loading and memory proof.
-6. Standalone native worker and Meshnet integration.
+6. GLM-specific boundary/KV/IndexShare semantics.
-7. Real target hardware route with no node individually able to admit the whole model.
+7. Standalone native worker and Meshnet integration.
-8. Locked target parity, usefulness, speed, failure, and cleanup evidence.
+8. Real target hardware route with no node individually able to admit the whole model.
+9. Locked target parity, usefulness, speed, failure, and cleanup evidence.
 
 ### Donor policy
 
@@ -204,7 +213,7 @@ Select a current exact upstream commit only after testing its stock GLM behavior
 
 ### DGR-018: certify whole-model GLM-5.2 runtime semantics
 
-On a 224+ GiB usable reference host or temporary equivalent:
+On a 256-GiB-class reference host with at least 224 GiB runtime-accessible memory after OS reservation, or a measured equivalent:
 
 1. verify all six `UD-IQ1_S` shards;
 2. load with a stock pinned runtime and capture tensor/metadata warnings;
@@ -223,7 +232,7 @@ Keep dense Llama as a cheap structural fixture. Implement authoritative owned-te
 
 ### DGR-006: architecture-defined boundary
 
-Implement named boundary bundles, F32 correctness lane, bounded fragmentation, and optional sidebands. Dense fixture parity proves the seam mechanism, not GLM certification.
+Implement named boundary bundles, F32 correctness lane, bounded fragmentation, and optional sidebands. Amend the decode fast path so it carries a versioned `TensorBundle` rather than one `NamedTensor`, while preserving a small one-tensor encoding. Define an explicit typed tail result for logits/token output and bind sampling/chat-template parameters to the recipe/request. Regenerate Python/C++ schema code and compatibility goldens. Dense fixture parity proves the seam mechanism, not GLM certification.
 
 Exit: two local processes can execute a small dense model with correct range ownership and boundary parity.
 
@@ -288,8 +297,10 @@ These thresholds are set before target execution.
 - All six source GGUF sizes and LFS SHA-256 values verify.
 - Every route node reports owned tensor names/bytes, layer range, endpoint role, backend, KV recipe, and patch fingerprint.
 - Union of owned tensors equals the certified runtime-required tensor inventory; unintended overlap is zero.
-- No node's admitted usable memory can hold the complete recipe.
+- No node's weight-plus-KV placement budget can hold the complete recipe.
-- Aggregate peak RSS/VRAM stays within admitted budgets with no swap-driven success claim.
+- Every node reserves at least `max(20% of physically usable memory, 8 GiB)` outside weight-plus-KV placement; measured peak scratch must remain inside that reserve.
+- Aggregate peak RSS/VRAM stays within physical budgets with no swap, overcommit, mmap-only, or double-counted unified-memory success claim.
+- Arithmetic-minimum topologies require exact contiguous tensor placement evidence; recommended alpha topology is 5×64 GiB or 3×96/128 GiB.
 - Unified RAM/VRAM is not double-counted.
 
 ### 5.2 Semantic correctness
@@ -302,8 +313,9 @@ These thresholds are set before target execution.
 
 ### 5.3 End-to-end target run
 
-- Context configured to 16,384 tokens.
+- Context configured to 16,384 tokens with Q8_0 MLA/indexer KV.
 - Fixed 4,096-token prompt lane completes prefill.
+- Route uses a same-switch wired network; 2.5 GbE is the alpha minimum and 10 GbE is recommended.
 - One Max-mode request generates at least 512 output tokens or reaches a valid natural EOS after at least 128 tokens.
 - Fixed coding, structured tool-call/JSON, and multi-step reasoning sentinels produce parseable, relevant outputs; raw prompts and outputs are retained for review.
 - OpenAI-compatible response includes stable model ID, finish reason, and token usage.
@@ -337,7 +349,7 @@ The next unattended work should run in this order:
 2. DGR-003 — exact recipe identity.
 3. DGR-004 — current llama.cpp pin and minimal patch harness.
 4. Run in parallel:
-   - DGR-018 — whole-model oracle on 224+ GiB usable memory.
+   - DGR-018 — whole-model oracle on a 256-GiB-class host with at least 224 GiB runtime-accessible memory.
    - DGR-005 and DGR-006 — generic range/boundary seam on local small fixtures.
 5. DGR-019 — GLM semantics and parity after both parallel lanes pass.
 6. DGR-007 through DGR-011 — native worker and real transport route.
@@ -351,11 +363,16 @@ The first external hardware blocker is DGR-018, but DGR-005/DGR-006 proceed loca
 Authoritative or primary:
 
 - Official model card and config: <https://huggingface.co/zai-org/GLM-5.2>
+- Official release/architecture blog: <https://z.ai/blog/glm-5.2>
+- Official code/documentation repository: <https://github.com/zai-org/GLM-5>
 - Official source revision API: <https://huggingface.co/api/models/zai-org/GLM-5.2>
 - Official GLM-5 technical report: <https://arxiv.org/abs/2602.15763>
 - Unsloth GGUF repository: <https://huggingface.co/unsloth/GLM-5.2-GGUF>
 - Unsloth local-run/quantization guide: <https://unsloth.ai/docs/models/glm-5.2>
 - llama.cpp GLM-5.2 support issue: <https://github.com/ggml-org/llama.cpp/issues/24730>
+- llama.cpp merged dense-MLA compatibility loader: <https://github.com/ggml-org/llama.cpp/pull/24770>
+- llama.cpp open GLM-5.2 DSA/IndexShare implementation: <https://github.com/ggml-org/llama.cpp/pull/25407>
+- llama.cpp merged generic CPU lightning indexer: <https://github.com/ggml-org/llama.cpp/pull/24231>
 - llama.cpp 1M-context discussion: <https://github.com/ggml-org/llama.cpp/discussions/24622>
 - IndexCache/IndexShare paper: <https://arxiv.org/abs/2603.12201>
 

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

@@ -104,6 +104,8 @@ Before a story is marked complete, run the full deterministic `pytest -q` suite
 **Acceptance Criteria:**
 - [ ] Head accepts token IDs and owns token embedding.
 - [ ] Middle/tail bypass token embedding and accept the named boundary bundle.
+- [ ] Amend the decode fast path from one `NamedTensor` to a versioned `TensorBundle`, preserving compact one-tensor compatibility and regenerating Python/C++ protocol goldens.
+- [ ] Define a typed tail logits/token result with sampling and chat-template/reasoning 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.
@@ -221,10 +223,11 @@ Before a story is marked complete, run the full deterministic `pytest -q` suite
 
 **Acceptance Criteria:**
 - [ ] Produce machine-readable target, resource, upstream-status, and immutable acceptance contracts without downloading full weights.
+- [ ] Distinguish the 224-GiB hard-fit floor from the recommended 5×64 or 3×96/128 topology, using Q8 KV, 20%/8-GiB node reserves, and a wired 2.5-GbE minimum.
 - [ ] Count unified RAM/VRAM once and test revision/shard/byte/threshold mutation failures.
 
 ### DGR-018: Certify whole-model GLM-5.2 runtime semantics
-**Description:** Establish a 224+ GiB usable-memory oracle for the exact target artifact before distributed parity work.
+**Description:** Establish the exact IQ1_S oracle on a 256-GiB-class host with at least 224 GiB runtime-accessible memory; lock Q8_0 MLA/indexer KV and native target semantics before distributed parity work.
 
 **Acceptance Criteria:**
 - [ ] Verify the complete artifact and prove native MoE/shared expert, DSA, IndexShare, KV, NextN policy, and Max-template behavior.

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

@@ -88,6 +88,8 @@ Do not introduce another scheduler/control plane from vLLM, Nakshatra, prima.cpp
 15. Model artifacts must remain on mounted-drive storage and never under `/home`.
 16. Unified system RAM and integrated-GPU memory are one physical pool and must never be double-counted for admission.
 17. Alpha requires native GLM-5.2 MoE, DSA, and IndexShare semantics; MTP/speculative decoding and 1M-context certification are post-alpha.
+18. DGR-006 amends the decode fast path to carry a versioned `TensorBundle` and defines a typed tail logits/token result; the current single-`NamedTensor` fast path is insufficient for GLM sidebands.
+19. Alpha reserves at least `max(20% of physical usable memory, 8 GiB)` per node outside weight-plus-Q8-KV placement and uses a same-switch wired 2.5 GbE minimum route.
 
 Changing one of these requires an explicit ADR update and human review, not an incidental story implementation.
 
@@ -215,7 +217,7 @@ Generated protobuf/C++ build outputs belong in build directories unless packagin
 | 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-006 | decode `TensorBundle` protocol amendment, typed tail-result contract, 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/` |

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

@@ -6,7 +6,7 @@ Status: active benchmark-gated implementation program.
 
 Serve the exact pinned GLM-5.2 `UD-IQ1_S` artifact in `reasoning_effort=max` mode across consumer machines with useful measured performance. Dense Llama is a structural fixture; the real multi-node GLM target is the alpha release gate.
 
-See **[GLM-5.2 Max distributed alpha roadmap](GLM-5.2-MAX-ALPHA-ROADMAP.md)** for the target identity, minimum hardware, immutable acceptance matrix, and revised execution order.
+See **[GLM-5.2 Max distributed alpha roadmap](GLM-5.2-MAX-ALPHA-ROADMAP.md)** for the target identity, minimum hardware, immutable acceptance matrix, and revised execution order. The 224-GiB figure is an experimental hard-fit floor; recommended topology is 5×64 GiB or 3×96/128 GiB after the required per-node reserve.
 
 ## Critical path
 

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

@@ -96,7 +96,9 @@ named tensor bundle
 compression/checksum
 ```
 
-Prefill tensors are split into bounded ordered frames. Decode messages carry one-step architecture boundary bundles and remain small.
+Prefill tensors are split into bounded ordered frames. Decode messages carry one-step architecture boundary bundles and remain small. DGR-006 amends the current v1 decode fast path—which carries only one `NamedTensor`—to carry a versioned `TensorBundle`, while preserving compact one-tensor encoding and explicit compatibility behavior.
+
+Tail completion is not inferred from an activation tensor name. The protocol exposes a typed logits and/or sampled-token result, and exact sampling parameters plus chat-template/reasoning mode are bound to request/runtime identity.
 
 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.
 

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

@@ -161,7 +161,7 @@ Scope boundary:
 - 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`.
+The public boundary uses a versioned named-tensor bundle rather than one anonymous tensor because architecture boundaries can require more than `hidden_states`. DGR-006 updates the current single-`NamedTensor` decode fast path to carry the same bundle semantics and adds an explicit typed tail logits/token result with sampling/template identity.
 
 Minimum identity:
 

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

@@ -23,6 +23,8 @@ As a Shard, I need to consume and emit the correct transformer boundary state so
 
 - [ ] 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.

.scratch/distributed-gguf-runtime/issues/17-lock-glm-5-2-max-target-and-alpha-contract.md

@@ -27,8 +27,10 @@ As a release owner, I need one exact GLM-5.2 Max target and immutable alpha cont
 - [ ] 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.
+- [ ] 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.

.scratch/distributed-gguf-runtime/issues/18-certify-whole-model-glm-5-2-runtime-semantics.md

@@ -23,7 +23,8 @@ As a runtime maintainer, I need a certified whole-model oracle for the exact low
 
 ## Acceptance criteria
 
-- [ ] 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.
+- [ ] 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.
@@ -47,7 +48,7 @@ As a runtime maintainer, I need a certified whole-model oracle for the exact low
 
 ## Finish contract
 
-- If 224+ GiB usable reference hardware is unavailable, write `evidence/DGR-018/BLOCKED.md` with exact preflight output; do not substitute a smaller model.
+- If a 256-GiB-class host with at least 224 GiB runtime-accessible memory is unavailable, write `evidence/DGR-018/BLOCKED.md` with exact preflight output; do not substitute a smaller model.
 - Preserve real failures and blockers; never fabricate output.
 - Emit `<promise>COMPLETE</promise>` only after the signed oracle evidence exists.
 

.scratch/distributed-gguf-runtime/issues/20-pass-real-distributed-glm-5-2-max-alpha.md

@@ -24,12 +24,14 @@ As an alpha user, I need the exact lowest-quant GLM-5.2 model to run in Max reas
 ## Acceptance criteria
 
 - [ ] 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.
+- [ ] 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; complete the fixed 4,096-token prefill lane and generate at least 512 output tokens or valid natural EOS after at least 128 tokens.
+- [ ] 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.

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

@@ -157,6 +157,8 @@
       "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.",
@@ -517,8 +519,10 @@
         "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.",
+        "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.",
@@ -545,7 +549,8 @@
       "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.",
+        "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.",
@@ -611,12 +616,14 @@
       "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.",
+        "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; complete the fixed 4,096-token prefill lane and generate at least 512 output tokens or valid natural EOS after at least 128 tokens.",
+        "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.",