From 8c87fae1acc9f046b43aceecf9a950dd2c808e52 Mon Sep 17 00:00:00 2001 From: Dobromir Popov Date: Mon, 27 Jul 2026 08:53:16 +0300 Subject: [PATCH] chore: restore canonical PRD metadata and projections --- .scratch/distributed-gguf-runtime/README.md | 2 +- ...ator-build-presets-and-native-ci-matrix.md | 3 + ...the-project-owned-shardengine-interface.md | 3 + ...mplement-deterministic-fake-shardengine.md | 3 + ...d-a-standalone-fake-c-grpc-shard-worker.md | 4 +- .scratch/distributed-gguf-runtime/prd.json | 260 +++++++++++++++++- 6 files changed, 271 insertions(+), 4 deletions(-) diff --git a/.scratch/distributed-gguf-runtime/README.md b/.scratch/distributed-gguf-runtime/README.md index 0875ee7..2b64b6c 100644 --- a/.scratch/distributed-gguf-runtime/README.md +++ b/.scratch/distributed-gguf-runtime/README.md @@ -1,6 +1,6 @@ # Distributed GGUF Runtime planning workspace -> **Specification status:** planning artifacts only. No distributed GGUF runtime is implemented. DGR-017 cleanup is complete; no runtime implementation story has completion credit. `prd.json` is authoritative. +> **Implementation status:** DGR-017 through DGR-033 have verified lane evidence, including a fixture-only standalone C++ gRPC worker. These lane checkpoints still require serialized integration and remote publication; they do not claim real model inference. `prd.json` is authoritative. ## Locked scope diff --git a/.scratch/distributed-gguf-runtime/issues/030-add-accelerator-build-presets-and-native-ci-matrix.md b/.scratch/distributed-gguf-runtime/issues/030-add-accelerator-build-presets-and-native-ci-matrix.md index 6bd44d4..2f3dab0 100644 --- a/.scratch/distributed-gguf-runtime/issues/030-add-accelerator-build-presets-and-native-ci-matrix.md +++ b/.scratch/distributed-gguf-runtime/issues/030-add-accelerator-build-presets-and-native-ci-matrix.md @@ -30,6 +30,9 @@ Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, - `git diff --check` passes. - Default tests are model-download-free, API-credit-free, and GPU-free. - Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit. +- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin. +- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`. +- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed. ## Evidence handoff diff --git a/.scratch/distributed-gguf-runtime/issues/031-introduce-the-project-owned-shardengine-interface.md b/.scratch/distributed-gguf-runtime/issues/031-introduce-the-project-owned-shardengine-interface.md index 9ac1cec..43dacd7 100644 --- a/.scratch/distributed-gguf-runtime/issues/031-introduce-the-project-owned-shardengine-interface.md +++ b/.scratch/distributed-gguf-runtime/issues/031-introduce-the-project-owned-shardengine-interface.md @@ -30,6 +30,9 @@ Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, - `git diff --check` passes. - Default tests are model-download-free, API-credit-free, and GPU-free. - Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit. +- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin. +- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`. +- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed. ## Evidence handoff diff --git a/.scratch/distributed-gguf-runtime/issues/032-implement-deterministic-fake-shardengine.md b/.scratch/distributed-gguf-runtime/issues/032-implement-deterministic-fake-shardengine.md index 3ab5802..f0d9502 100644 --- a/.scratch/distributed-gguf-runtime/issues/032-implement-deterministic-fake-shardengine.md +++ b/.scratch/distributed-gguf-runtime/issues/032-implement-deterministic-fake-shardengine.md @@ -30,6 +30,9 @@ Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, - `git diff --check` passes. - Default tests are model-download-free, API-credit-free, and GPU-free. - Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit. +- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin. +- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`. +- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed. ## Evidence handoff diff --git a/.scratch/distributed-gguf-runtime/issues/033-build-a-standalone-fake-c-grpc-shard-worker.md b/.scratch/distributed-gguf-runtime/issues/033-build-a-standalone-fake-c-grpc-shard-worker.md index c01c1c4..77bb50a 100644 --- a/.scratch/distributed-gguf-runtime/issues/033-build-a-standalone-fake-c-grpc-shard-worker.md +++ b/.scratch/distributed-gguf-runtime/issues/033-build-a-standalone-fake-c-grpc-shard-worker.md @@ -1,7 +1,7 @@ # DGR-033: Build a standalone fake C++ gRPC Shard worker -- **Status / triage:** completed; `ready-for-agent`; `passes: true` +- **Status / triage:** completed; `passes: true` - **Execution mode:** `AFK` - **Milestone:** `M1` - **Dependencies:** `DGR-022`, `DGR-024`, `DGR-032` @@ -36,4 +36,4 @@ Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, ## Evidence handoff -Verified evidence: `.scratch/distributed-gguf-runtime/evidence/DGR-033/README.md`. All acceptance criteria and applicable shared gates passed after the Codex BLOCK repair and fresh native/Python verification. Legacy evidence remains provenance only. +Verified evidence: `.scratch/distributed-gguf-runtime/evidence/DGR-033/README.md`. Legacy evidence remains provenance only and grants no implementation completion credit. diff --git a/.scratch/distributed-gguf-runtime/prd.json b/.scratch/distributed-gguf-runtime/prd.json index 773fef9..a57091c 100644 --- a/.scratch/distributed-gguf-runtime/prd.json +++ b/.scratch/distributed-gguf-runtime/prd.json @@ -1,7 +1,265 @@ { "name": "Distributed GGUF Runtime", - "description": "Benchmark-gated distributed GGUF Shards using existing Meshnet control-plane routing and a standalone C++ gRPC worker around pinned upstream llama.cpp, targeting DeepSeek V4 Flash without hardcoded quantization or topology.", "branchName": "ralph/distributed-gguf-runtime", + "description": "Benchmark-gated distributed GGUF Shards using existing Meshnet control-plane routing and a standalone C++ gRPC worker around pinned upstream llama.cpp, targeting DeepSeek V4 Flash without hardcoded quantization or topology.", + "sourceOfTruth": "This prd.json is authoritative. Generated issue Markdown and planning summaries are projections and must not override it. DGR-017 and DGR-018 are complete; all later stories remain unimplemented specifications with passes=false.", + "qualityGates": { + "universal": [ + "Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.", + "`git diff --check` passes.", + "Default tests are model-download-free, API-credit-free, and GPU-free.", + "Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit." + ], + "native": [ + "Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin." + ], + "realModelHardware": [ + "Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`." + ], + "scope": [ + "Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed." + ] + }, + "metadataSchema": { + "requiredStoryFields": [ + "id", + "title", + "description", + "acceptanceCriteria", + "priority", + "passes", + "milestone", + "executionMode", + "labels", + "triage", + "evidenceClass", + "evidencePath", + "hardware", + "model", + "upstream", + "dependsOn", + "notes", + "blocks" + ], + "optionalStoryFields": [ + "completionNotes" + ], + "idRange": "DGR-017..DGR-071 inclusive", + "triageValues": [ + "ready-for-agent", + "ready-for-human" + ], + "executionModeValues": [ + "AFK", + "HITL" + ], + "evidenceClassValues": [ + "model-free", + "fixture", + "real-model", + "real-hardware", + "release" + ], + "hardwareValues": [ + "none", + "optional", + "required" + ], + "upstreamValues": [ + "yes", + "no", + "conditional" + ], + "typeDerivation": "A story type is derived from its type: label; gate: stories derive release-gate.", + "labelConventions": "Reserved prefixes include type:, priority:, area:, gate:, and ready-for-agent/ready-for-human triage labels; at most one type: and one priority: label are allowed.", + "generatedArtifactDisclaimer": "", + "dependencyRules": "Dependencies reference existing numerically earlier IDs; graph is acyclic. blocks is mechanically derived from dependsOn.", + "authorityRule": "Generated issue files state that prd.json is authoritative and cannot independently claim completion or override it." + }, + "milestones": [ + { + "id": "M0", + "name": "Truth and contracts", + "stories": "DGR-017..DGR-020", + "outcome": "Reconciled legacy truth, canonical metadata, immutable gates, and a controlled whole-model baseline." + }, + { + "id": "M1", + "name": "Protocol and native substrate", + "stories": "DGR-021..DGR-033", + "outcome": "Versioned gRPC protocol, exact identities/artifacts, pinned upstream, reproducible builds, ShardEngine, and fake worker." + }, + { + "id": "M2", + "name": "Dense vertical proof", + "stories": "DGR-034..DGR-043", + "outcome": "Dense ranged execution, parity, local state, worker integration, and GGUF inputs to existing routing." + }, + { + "id": "M3", + "name": "DeepSeek V4 Flash alpha", + "stories": "DGR-044..DGR-054", + "outcome": "Pinned V4 adapter around upstream llama.cpp, real route certification, and pre-locked alpha decision with MTP off." + }, + { + "id": "M4", + "name": "Performance and beta hardening", + "stories": "DGR-055..DGR-067", + "outcome": "Batching, backpressure, recovery, scale certification, optimization, MTP, and hardware matrix." + }, + { + "id": "M5", + "name": "Release and maintenance", + "stories": "DGR-068..DGR-071", + "outcome": "Reproducible packages, upstream collaboration, beta decision, and sustainable recertification." + } + ], + "supersededStories": { + "DGR-001": { + "newIds": [ + "DGR-019", + "DGR-020", + "DGR-054", + "DGR-070" + ], + "disposition": "Benchmark scaffold/evidence may be audited; old pass state is void." + }, + "DGR-002": { + "newIds": [ + "DGR-021", + "DGR-022", + "DGR-023", + "DGR-024" + ], + "disposition": "Split protocol, lifecycle, code generation, and fake transport." + }, + "DGR-003": { + "newIds": [ + "DGR-025" + ], + "disposition": "Replaced by exact artifact/runtime compatibility identity." + }, + "DGR-004": { + "newIds": [ + "DGR-027", + "DGR-028", + "DGR-029", + "DGR-030", + "DGR-071" + ], + "disposition": "Split provenance, patch stack, builds, and maintenance." + }, + "DGR-005": { + "newIds": [ + "DGR-034", + "DGR-045" + ], + "disposition": "Dense and V4 ownership separated." + }, + "DGR-006": { + "newIds": [ + "DGR-031", + "DGR-035", + "DGR-036", + "DGR-046", + "DGR-047", + "DGR-048", + "DGR-049" + ], + "disposition": "Engine, dense boundary, V4 typed boundary, and local-state adapters separated." + }, + "DGR-007": { + "newIds": [ + "DGR-038", + "DGR-049" + ], + "disposition": "Replaced by session/epoch-keyed local KV and V4 auxiliary state." + }, + "DGR-008": { + "newIds": [ + "DGR-032", + "DGR-033", + "DGR-037" + ], + "disposition": "Old implementation/evidence absent; no completion credit transfers." + }, + "DGR-009": { + "newIds": [ + "DGR-040", + "DGR-041", + "DGR-042", + "DGR-043" + ], + "disposition": "Supervision, registration, relay, and routing-input integration separated." + }, + "DGR-010": { + "newIds": [ + "DGR-036", + "DGR-039", + "DGR-052" + ], + "disposition": "Fixture, dense real acceptance, and V4 parity separated." + }, + "DGR-011": { + "newIds": [ + "DGR-053", + "DGR-061", + "DGR-062", + "DGR-067" + ], + "disposition": "Replaced by scenario-based real 2–4, existing-routing 10+, real 10+, and backend certification." + }, + "DGR-012": { + "newIds": [ + "DGR-055", + "DGR-056", + "DGR-057" + ], + "disposition": "Batching, admission/backpressure, and benchmarking separated." + }, + "DGR-013": { + "newIds": [ + "DGR-058", + "DGR-059" + ], + "disposition": "Failure semantics and restart/re-prefill recovery separated." + }, + "DGR-014": { + "newIds": [ + "DGR-019", + "DGR-054", + "DGR-070" + ], + "disposition": "Replaced by immutable performance, alpha, and beta gates." + }, + "DGR-015": { + "newIds": [ + "DGR-044", + "DGR-045", + "DGR-046", + "DGR-047", + "DGR-048", + "DGR-049", + "DGR-050", + "DGR-051", + "DGR-052", + "DGR-053", + "DGR-054", + "DGR-060", + "DGR-065", + "DGR-066", + "DGR-067" + ], + "disposition": "Qwen target superseded by DeepSeek V4 Flash; no old completion transfers." + }, + "DGR-016": { + "newIds": [ + "DGR-069", + "DGR-071" + ], + "disposition": "Upstream collaboration and ongoing maintenance separated." + } + }, "userStories": [ { "id": "DGR-017",