# 17 — Lock the GLM-5.2 Max target and alpha contract

Status: ready-for-agent

## Mandatory fresh-session context

- Read [RALPH-CONTEXT.md](../RALPH-CONTEXT.md), [GLM-5.2-MAX-ALPHA-ROADMAP.md](../GLM-5.2-MAX-ALPHA-ROADMAP.md), and this issue completely before changing code.
- This issue is `DGR-017` in [prd.json](../prd.json).
- Read the evidence README for every dependency listed below.
- Inspect current code, upstream sources, and `git status`; historical text and previous agent claims are not evidence.

## Description

As 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.

## Expected durable outputs

- Machine-readable official/GGUF target manifest with revisions, filenames, sizes, and resolved hashes
- Architecture/config/chat-template snapshot and source links
- Deterministic memory/KV/network planner with unified-memory de-duplication
- Current llama.cpp and donor-support status report
- Immutable machine-readable alpha acceptance contract
- `evidence/DGR-017/README.md`

## Acceptance criteria

- [ ] 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.

## Dependency handoff

- `DGR-001` and `DGR-002` must have `passes: true`; read their evidence READMEs and verify referenced files/commands.

## Finish contract

- Create the task evidence directory and durable handoff required above.
- Preserve real failures and blockers; never fabricate source, benchmark, model, test, or hardware output.
- Change this issue to `Status: done` only after all criteria pass.
- Emit `<promise>COMPLETE</promise>` only after the evidence handoff exists.

## References

- [GLM-5.2 Max alpha roadmap](../GLM-5.2-MAX-ALPHA-ROADMAP.md)
- [Ralph execution context](../RALPH-CONTEXT.md)
- [Current architecture](../architecture.md)