From 766e480ba5ea3d075effba25c8209d555dba1bab Mon Sep 17 00:00:00 2001 From: Dobromir Popov Date: Sat, 25 Jul 2026 22:38:00 +0300 Subject: [PATCH] story: DGR-033 Build a standalone fake C++ gRPC Shard worker --- .ralph-lane/controller.log | 3 + .ralph-lane/controller.pid | 1 + .ralph-lane/current-prd.json | 2210 +++++++++++++++++ .../evidence/DGR-033/README.md | 208 ++ ...d-a-standalone-fake-c-grpc-shard-worker.md | 17 +- .scratch/distributed-gguf-runtime/prd.json | 5 +- packages/node/native/CMakeLists.txt | 15 + packages/node/native/worker/fake_engine.h | 164 ++ packages/node/native/worker/shard_service.cpp | 364 +++ packages/node/native/worker/shard_service.h | 85 + .../node/native/worker/shard_worker_main.cpp | 302 +++ tests/test_native_shard_worker.py | 498 ++++ 12 files changed, 3860 insertions(+), 12 deletions(-) create mode 100644 .ralph-lane/controller.log create mode 100644 .ralph-lane/controller.pid create mode 100644 .ralph-lane/current-prd.json create mode 100644 .scratch/distributed-gguf-runtime/evidence/DGR-033/README.md create mode 100644 packages/node/native/worker/fake_engine.h create mode 100644 packages/node/native/worker/shard_service.cpp create mode 100644 packages/node/native/worker/shard_service.h create mode 100644 packages/node/native/worker/shard_worker_main.cpp create mode 100644 tests/test_native_shard_worker.py diff --git a/.ralph-lane/controller.log b/.ralph-lane/controller.log new file mode 100644 index 0000000..89e6c61 --- /dev/null +++ b/.ralph-lane/controller.log @@ -0,0 +1,3 @@ +[2026-07-25T19:19:43+00:00] START lane=opus agent=claude model=opus branch=ralph/distributed-gguf-opus +[2026-07-25T19:19:43+00:00] CLAIM DGR-033: Build a standalone fake C++ gRPC Shard worker +[2026-07-25T19:19:43+00:00] $ ralph-tui run --prd /run/media/popov/d/DEV/repos/d-popov.com/AI/.claude/worktrees/distributed-gguf-opus/.ralph-lane/current-prd.json --agent claude --model opus --iterations 1 --no-tui --no-setup --verify --cwd /run/media/popov/d/DEV/repos/d-popov.com/AI/.claude/worktrees/distributed-gguf-opus --output-dir /run/media/popov/d/DEV/repos/d-popov.com/AI/.claude/worktrees/distributed-gguf-opus/.ralph-lane/iterations --progress-file /run/media/popov/d/DEV/repos/d-popov.com/AI/.claude/worktrees/distributed-gguf-opus/.ralph-lane/progress.md diff --git a/.ralph-lane/controller.pid b/.ralph-lane/controller.pid new file mode 100644 index 0000000..8479f9a --- /dev/null +++ b/.ralph-lane/controller.pid @@ -0,0 +1 @@ +205508 diff --git a/.ralph-lane/current-prd.json b/.ralph-lane/current-prd.json new file mode 100644 index 0000000..cf36dcf --- /dev/null +++ b/.ralph-lane/current-prd.json @@ -0,0 +1,2210 @@ +{ + "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", + "userStories": [ + { + "id": "DGR-017", + "title": "Reconcile and clean the superseded DGR backlog", + "priority": 1, + "milestone": "M0", + "executionMode": "AFK", + "labels": [ + "area:provenance", + "area:cleanup", + "type:audit", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "model-free", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-017/README.md", + "hardware": "none", + "model": "generic", + "upstream": "no", + "dependsOn": [], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/017-reconcile-and-clean-the-superseded-dgr-backlog.md`, and evidence READMEs for dependencies (none) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Audit implementation reality, void inherited completion credit, and clean misleading backlog/stub baggage while preserving attributable evidence and accepted research.", + "acceptanceCriteria": [ + "Compare the branch, old DGR-001..016 issue/pass states, evidence, and actual runtime sources; classify each output as reusable, reference-only, blocked, obsolete, or absent.", + "Record an authoritative old-to-new disposition and provenance; explicitly give no completion credit to any new story and note absent implementation/evidence.", + "Remove or archive only artifacts the audit proves obsolete while preserving accepted ADRs, useful research, raw benchmark evidence, and attributable reusable work.", + "Protect ignored build workspaces, generated protobuf outputs, Ralph logs, and model artifacts from accidental commits, and document every retained legacy artifact.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative.", + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/017-reconcile-and-clean-the-superseded-dgr-backlog.md; prd.json is authoritative.", + "blocks": [ + "DGR-018", + "DGR-019", + "DGR-027", + "DGR-054" + ] + }, + { + "id": "DGR-018", + "title": "Define canonical Ralph and Gitea metadata schema", + "priority": 2, + "milestone": "M0", + "executionMode": "AFK", + "labels": [ + "area:planning", + "area:gitea", + "type:infrastructure", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "model-free", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-018/README.md", + "hardware": "none", + "model": "generic", + "upstream": "no", + "dependsOn": [ + "DGR-017" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/018-define-canonical-ralph-and-gitea-metadata-schema.md`, and evidence READMEs for dependencies (DGR-017) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Make `prd.json` the validated source from which Markdown and Gitea issues can later be generated losslessly.", + "acceptanceCriteria": [ + "Define fields for stable ID/title, labels, milestone, type, `dependsOn`, derived `blocks`, triage, evidence class, and hardware/model/upstream flags.", + "Validate that all stories start `passes: false`, use known dependencies, and have unique stable IDs.", + "Reject cycles, missing dependencies, mismatched generated `blocks`, duplicate titles/IDs, and generated artifacts claiming authority over `prd.json`.", + "Add deterministic model-free tests for parse, validation, and generation round trips.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative.", + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/018-define-canonical-ralph-and-gitea-metadata-schema.md; prd.json is authoritative.", + "blocks": [ + "DGR-021", + "DGR-025" + ] + }, + { + "id": "DGR-019", + "title": "Lock alpha and beta performance contracts", + "priority": 3, + "milestone": "M0", + "executionMode": "HITL", + "labels": [ + "area:performance", + "type:contract", + "priority:p0", + "gate:hitl", + "ready-for-human" + ], + "evidenceClass": "release", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-019/README.md", + "hardware": "required", + "model": "generic+deepseek-v4", + "upstream": "no", + "dependsOn": [ + "DGR-017" + ], + "triage": "ready-for-human", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/019-lock-alpha-and-beta-performance-contracts.md`, and evidence READMEs for dependencies (DGR-017) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Freeze useful speed, correctness, memory-fit, and stop/go thresholds before implementation results are visible.", + "acceptanceCriteria": [ + "Define controlled safetensors, whole-model GGUF, dense distributed GGUF, and V4 Flash distributed lanes with fixed prompts, context/output lengths, sampling, concurrency, hardware, and metrics.", + "Alpha requires correctness plus a human-approved useful-speed threshold; beta adds concurrency, long-context, failure, and sustained-throughput thresholds.", + "Separate quantization/model-fit gains from runtime, transport, batching, and kernel gains.", + "Treat quants and 2–4/10+ stage counts only as named certification scenarios; no product logic may hardcode them.", + "Lock thresholds and stop conditions in versioned machine-readable data before benchmark result ingestion.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/019-lock-alpha-and-beta-performance-contracts.md; prd.json is authoritative.", + "blocks": [ + "DGR-020", + "DGR-044", + "DGR-054" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-020", + "title": "Run the controlled whole-model GGUF baseline", + "priority": 4, + "milestone": "M0", + "executionMode": "HITL", + "labels": [ + "area:performance", + "type:benchmark", + "priority:p0", + "gate:hitl", + "ready-for-human" + ], + "evidenceClass": "real-hardware", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-020/README.md", + "hardware": "required", + "model": "generic", + "upstream": "no", + "dependsOn": [ + "DGR-019" + ], + "triage": "ready-for-human", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/020-run-the-controlled-whole-model-gguf-baseline.md`, and evidence READMEs for dependencies (DGR-019) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Execute the locked safetensors and whole-model llama.cpp lanes before distributed implementation results can influence the decision.", + "acceptanceCriteria": [ + "Run the exact DGR-019 safetensors and whole-model llama.cpp benchmark lanes with locked prompts, lengths, sampling, concurrency, hardware, and artifact/runtime identities.", + "Record raw machine-readable correctness, TTFT, prefill/decode, throughput, latency, memory, artifact-size, failure, and quality-drift metrics without ingesting distributed implementation results.", + "Separate quantization/model-fit effects from runtime/kernel effects and preserve failed or unavailable lanes honestly.", + "Publish a threshold-based `go`, `optimize baseline`, or `stop` decision without changing the locked contract.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/020-run-the-controlled-whole-model-gguf-baseline.md; prd.json is authoritative.", + "blocks": [ + "DGR-054" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-021", + "title": "Define the versioned named-tensor stream envelope", + "priority": 5, + "milestone": "M1", + "executionMode": "AFK", + "labels": [ + "area:protocol", + "type:infrastructure", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "model-free", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-021/README.md", + "hardware": "none", + "model": "generic", + "upstream": "no", + "dependsOn": [ + "DGR-018" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/021-define-the-versioned-named-tensor-stream-envelope.md`, and evidence READMEs for dependencies (DGR-018) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Establish the backend-neutral protobuf envelope used by direct and relayed Shard activation traffic.", + "acceptanceCriteria": [ + "Define schema version, request/work ID, route session/epoch, shard range/effective start, phase, position, and idempotency step.", + "Define named tensors with shape, dtype, byte order, bounded fragments, compression identity, and checksum.", + "Reserve extensible fields for token-ID sidebands, architecture state, recurrent state, and MTP without claiming implementations.", + "Add deterministic serialization, fragmentation, checksum, unknown-field, and size-limit tests.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative.", + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/021-define-the-versioned-named-tensor-stream-envelope.md; prd.json is authoritative.", + "blocks": [ + "DGR-022", + "DGR-023", + "DGR-025", + "DGR-031", + "DGR-035", + "DGR-046" + ] + }, + { + "id": "DGR-022", + "title": "Define Shard lifecycle and structured status RPCs", + "priority": 6, + "milestone": "M1", + "executionMode": "AFK", + "labels": [ + "area:protocol", + "area:lifecycle", + "type:infrastructure", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "model-free", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-022/README.md", + "hardware": "none", + "model": "generic", + "upstream": "no", + "dependsOn": [ + "DGR-021" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/022-define-shard-lifecycle-and-structured-status-rpcs.md`, and evidence READMEs for dependencies (DGR-021) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Complete the gRPC contract for worker capability, health, sessions, cancellation, release, and metrics.", + "acceptanceCriteria": [ + "Define capability, health, bidirectional session stream, cancellation, release, and metrics RPCs.", + "Specify deadlines, cancellation propagation, bounded flow control, cache expectations/results, and structured error taxonomy.", + "Specify TLS/auth hooks without moving Meshnet authentication or billing into the worker.", + "Add compatibility tests for supported versions and fail-closed tests for unsupported versions and malformed lifecycle transitions.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Completed from isolated DGR-022 Ralph worktree; verified with 17 focused pytest cases and retained DGR-021 envelope compatibility.", + "blocks": [ + "DGR-024", + "DGR-033", + "DGR-037" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-023", + "title": "Make Python and C++ protobuf generation reproducible", + "priority": 7, + "milestone": "M1", + "executionMode": "AFK", + "labels": [ + "area:protocol", + "area:build", + "type:tooling", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "model-free", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-023/README.md", + "hardware": "none", + "model": "generic", + "upstream": "no", + "dependsOn": [ + "DGR-021" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/023-make-python-and-c-protobuf-generation-reproducible.md`, and evidence READMEs for dependencies (DGR-021) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Generate identical Python/C++ protocol bindings without manual copying or checked-in build debris.", + "acceptanceCriteria": [ + "Pin protoc, gRPC, and plugin versions or declare a verified compatible range.", + "Generate Python and C++ bindings into out-of-tree build/package locations through documented commands.", + "Add Python↔C++ round-trip and descriptor compatibility tests.", + "A clean checkout regenerates bindings deterministically or fails with an actionable toolchain error.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Completed from Gitea #7 after controller provisioned and exercised the exact Python/C++ toolchains. Verified deterministic generation, native CMake/CTest, Python↔C++ byte parity, compileall, and diff checks; fixed relative bootstrap prefix resolution.", + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative.", + "blocks": [ + "DGR-024", + "DGR-037" + ] + }, + { + "id": "DGR-024", + "title": "Implement real generated-gRPC protocol harness", + "priority": 8, + "milestone": "M1", + "executionMode": "AFK", + "labels": [ + "area:protocol", + "area:testing", + "type:vertical-slice", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "model-free", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-024/README.md", + "hardware": "none", + "model": "none", + "upstream": "no", + "dependsOn": [ + "DGR-022", + "DGR-023" + ], + "triage": "ready-for-agent", + "description": "Build a real generated-gRPC protocol harness around the versioned shard_runtime.proto contract. Use generated Python and C++ stubs over an actual localhost transport and real process lifecycle; exercise captured deterministic protocol vectors and serialized protobuf bytes before a real model worker exists. Do not implement an in-memory fake transport, synthetic model outputs, or a production-looking stub/demo service.", + "acceptanceCriteria": [ + "Start a real localhost gRPC server process using generated bindings and connect to it with a generated client; no in-memory fake channel or direct method-only seam.", + "Exercise prefill fragments, decode frames, release, cancel, flow-control, deadlines, malformed input, checksum failure, duplicates, and stale epochs using serialized protocol messages and captured deterministic vectors.", + "Prove direct and opaque-relay paths preserve identical protobuf bytes by recording and comparing actual wire frames at both boundaries.", + "Use real process/socket lifecycle and fail closed on transport, schema, epoch, size, cache, and deadline violations; do not claim model or accelerator behavior that is not exercised.", + "Applicable shared quality gates pass, and evidence records exact commands, raw outputs, generated artifact identities, wire-frame hashes, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/024-implement-real-generated-grpc-protocol-harness.md; prd.json is authoritative.", + "blocks": [ + "DGR-033", + "DGR-042" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-025", + "title": "Define exact artifact and runtime recipe identity", + "priority": 9, + "milestone": "M1", + "executionMode": "AFK", + "labels": [ + "area:identity", + "area:admission", + "type:domain", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "model-free", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-025/README.md", + "hardware": "none", + "model": "generic", + "upstream": "no", + "dependsOn": [ + "DGR-018", + "DGR-021" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/025-define-exact-artifact-and-runtime-recipe-identity.md`, and evidence READMEs for dependencies (DGR-018, DGR-021) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Ensure the tracker and worker only combine numerically and operationally compatible shards.", + "acceptanceCriteria": [ + "Fingerprint source artifact SHA, tokenizer revision, architecture adapter/version, boundary schema, runtime pin/patch stack, backend, quant, activation/compute dtype, and KV/state layout.", + "Bind each shard to an exact half-open range without hardcoding a topology or quant.", + "Fail closed on any artifact, adapter, boundary, cache, backend, or runtime mismatch.", + "Unsupported recipes remain registered-but-dark until real-hardware evidence certifies them.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/025-define-exact-artifact-and-runtime-recipe-identity.md; prd.json is authoritative.", + "blocks": [ + "DGR-026", + "DGR-031", + "DGR-041", + "DGR-044" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-026", + "title": "Provision exact split-GGUF artifacts outside /home", + "priority": 10, + "milestone": "M1", + "executionMode": "AFK", + "labels": [ + "area:artifacts", + "area:provenance", + "type:tooling", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "fixture", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-026/README.md", + "hardware": "none", + "model": "generic", + "upstream": "no", + "dependsOn": [ + "DGR-025" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/026-provision-exact-split-gguf-artifacts-outside-home.md`, and evidence READMEs for dependencies (DGR-025) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Make exact split-GGUF inputs reproducibly available from mounted-drive storage without embedding a quantization or topology assumption in product code.", + "acceptanceCriteria": [ + "Create an exact manifest that binds the source artifact, tokenizer/revision, every split file name, size, range/role, and cryptographic hash.", + "Provide resumable, hash-verifying download/provision tooling targeting configured mounted-drive storage; refuse paths under `/home` and incomplete or mismatched splits.", + "Keep quantization and split topology as manifest/recipe inputs with no hardcoded quant, node count, or range layout.", + "Add deterministic model-download-free tests using tiny local split fixtures, including interrupted resume, missing split, hash mismatch, and `/home` rejection.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/026-provision-exact-split-gguf-artifacts-outside-home.md; prd.json is authoritative.", + "blocks": [ + "DGR-044", + "DGR-045" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-027", + "title": "Add exact llama.cpp provenance manifest and fetch workspace", + "priority": 11, + "milestone": "M1", + "executionMode": "AFK", + "labels": [ + "area:upstream", + "area:build", + "type:provenance", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "model-free", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-027/README.md", + "hardware": "none", + "model": "generic", + "upstream": "yes", + "dependsOn": [ + "DGR-017" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/027-add-exact-llama-cpp-provenance-manifest-and-fetch-workspace.md`, and evidence READMEs for dependencies (DGR-017) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Pin llama.cpp exactly through an in-repo manifest while fetching source only into an ignored build workspace.", + "acceptanceCriteria": [ + "Manifest records upstream URL, exact commit, expected source archive/tree hash, license, and retrieval method.", + "Fetch tooling verifies identity before use and refuses an unpinned branch/tag.", + "Source is fetched into an ignored build workspace; no submodule, vendored source tree, or permanent fork is introduced.", + "Offline reuse is supported only after the cached tree’s exact identity is verified.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Completed from Gitea #11 via the Terra Ralph lane; independently reviewed after fail-closed cache identity hardening. Verified 7 focused tests, exact real-cache reuse, compileall, and diff-check. The pre-existing malformed 0002 patch is handed to DGR-028.", + "blocks": [ + "DGR-028", + "DGR-029", + "DGR-044" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-028", + "title": "Implement numbered patch-stack apply and verification", + "priority": 12, + "milestone": "M1", + "executionMode": "AFK", + "labels": [ + "area:upstream", + "area:patches", + "type:tooling", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "model-free", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-028/README.md", + "hardware": "none", + "model": "generic", + "upstream": "yes", + "dependsOn": [ + "DGR-027" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/028-implement-numbered-patch-stack-apply-and-verification.md`, and evidence READMEs for dependencies (DGR-027) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Maintain a minimal auditable llama.cpp delta with one numbered patch per concern.", + "acceptanceCriteria": [ + "Add deterministic apply/check/reverse verification against the exact manifest pin.", + "Separate range loading, boundary I/O, filtered state, and worker hooks into scoped patches.", + "Record upstream file/API assumptions and fail with the first incompatible patch when the pin changes.", + "Verify license/attribution and prove no Meshnet routing, billing, relay, or authentication code enters the patch stack.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/028-implement-numbered-patch-stack-apply-and-verification.md; prd.json is authoritative.", + "blocks": [ + "DGR-029", + "DGR-034", + "DGR-069" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-029", + "title": "Create the native CMake skeleton and deterministic CPU lane", + "priority": 13, + "milestone": "M1", + "executionMode": "AFK", + "labels": [ + "area:build", + "type:toolchain", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "model-free", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-029/README.md", + "hardware": "none", + "model": "generic", + "upstream": "yes", + "dependsOn": [ + "DGR-027", + "DGR-028" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/029-create-the-native-cmake-skeleton-and-deterministic-cpu-lane.md`, and evidence READMEs for dependencies (DGR-027, DGR-028) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Establish an out-of-tree standalone native build with a deterministic CPU lane before accelerator matrix work.", + "acceptanceCriteria": [ + "Create the standalone native CMake target/skeleton and isolated out-of-tree configure/build preset for CPU.", + "Build and run a deterministic model-free CPU smoke/CTest lane from a clean checkout with actionable toolchain failures.", + "Keep fetched upstream sources, generated bindings, and all build outputs ignored and out of tree.", + "Ensure build success alone does not advertise any backend/model/recipe capability.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/029-create-the-native-cmake-skeleton-and-deterministic-cpu-lane.md; prd.json is authoritative.", + "blocks": [ + "DGR-030", + "DGR-034" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-030", + "title": "Add accelerator build presets and native CI matrix", + "priority": 14, + "milestone": "M1", + "executionMode": "AFK", + "labels": [ + "area:build", + "area:hardware", + "type:toolchain", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "model-free", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-030/README.md", + "hardware": "optional", + "model": "generic", + "upstream": "yes", + "dependsOn": [ + "DGR-029" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/030-add-accelerator-build-presets-and-native-ci-matrix.md`, and evidence READMEs for dependencies (DGR-029) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Compile all required accelerator lanes reproducibly while keeping untested real-hardware capabilities registered-dark.", + "acceptanceCriteria": [ + "Add isolated out-of-tree presets for CUDA, ROCm, Vulkan, and Metal without changing the deterministic CPU default.", + "Add a native CI/build matrix that reports unavailable SDKs as explicit unavailable/skipped lanes rather than false success.", + "Compile each available lane and preserve exact compiler, SDK, upstream pin, patch-stack, and build-option evidence.", + "Keep every backend/model/recipe lane registered-dark until a separate real-hardware certification record exists.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/030-add-accelerator-build-presets-and-native-ci-matrix.md; prd.json is authoritative.", + "blocks": [ + "DGR-053", + "DGR-067", + "DGR-068" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-031", + "title": "Introduce the project-owned `ShardEngine` interface", + "priority": 15, + "milestone": "M1", + "executionMode": "AFK", + "labels": [ + "area:engine", + "type:architecture", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "model-free", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-031/README.md", + "hardware": "none", + "model": "generic", + "upstream": "no", + "dependsOn": [ + "DGR-021", + "DGR-025" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/031-introduce-the-project-owned-shardengine-interface.md`, and evidence READMEs for dependencies (DGR-021, DGR-025) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Isolate worker/protocol code from llama.cpp internals behind a stable project-owned engine contract.", + "acceptanceCriteria": [ + "Define load, capabilities, prefill/decode, boundary/logits result, cancel, release, health, and metrics operations.", + "Use project-owned request/result/state types; expose no `ggml_tensor`, llama context, scheduler, or ABI-owned structure.", + "Reserve typed MTP and architecture auxiliary-state hooks without enabling them.", + "Add contract tests proving fake and future llama implementations obey identical lifecycle semantics.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/031-introduce-the-project-owned-shardengine-interface.md; prd.json is authoritative.", + "blocks": [ + "DGR-032", + "DGR-034", + "DGR-035", + "DGR-037" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-032", + "title": "Implement deterministic fake `ShardEngine`", + "priority": 16, + "milestone": "M1", + "executionMode": "AFK", + "labels": [ + "area:engine", + "area:testing", + "type:fixture", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "fixture", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-032/README.md", + "hardware": "none", + "model": "fake", + "upstream": "no", + "dependsOn": [ + "DGR-031" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/032-implement-deterministic-fake-shardengine.md`, and evidence READMEs for dependencies (DGR-031) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Provide an engine fixture that deterministically transforms typed boundary bundles and session state.", + "acceptanceCriteria": [ + "Support head, middle, tail, prefill, decode, cancellation, and release with deterministic outputs.", + "Model isolated session/epoch state and deterministic cache-miss/stale-epoch failures.", + "Support configurable delay, memory pressure, malformed output, and crash injection.", + "Contract tests distinguish fixture evidence from real-model certification.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/032-implement-deterministic-fake-shardengine.md; prd.json is authoritative.", + "blocks": [ + "DGR-033" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-033", + "title": "Build a standalone fake C++ gRPC Shard worker", + "priority": 17, + "milestone": "M1", + "executionMode": "AFK", + "labels": [ + "area:worker", + "area:grpc", + "type:vertical-slice", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "fixture", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-033/README.md", + "hardware": "none", + "model": "fake", + "upstream": "no", + "dependsOn": [ + "DGR-022", + "DGR-024", + "DGR-032" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/033-build-a-standalone-fake-c-grpc-shard-worker.md`, and evidence READMEs for dependencies (DGR-022, DGR-024, DGR-032) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Prove the standalone worker process, stream, lifecycle, and supervision shape before llama.cpp integration.", + "acceptanceCriteria": [ + "A standalone C++ executable serves the complete lifecycle and stream RPC contract using the fake engine.", + "Python integration tests cover startup, health, capability, fragmented prefill, decode, release, cancellation, and graceful shutdown.", + "Bounded messages, deadlines, flow control, and independent session cancellation are enforced.", + "The worker exposes neither llama.cpp RPC nor arbitrary graph execution.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/033-build-a-standalone-fake-c-grpc-shard-worker.md; prd.json is authoritative.", + "blocks": [ + "DGR-036", + "DGR-040" + ], + "completionNotes": "Completed by agent" + }, + { + "id": "DGR-034", + "title": "Implement dense-Llama range-aware GGUF ownership", + "priority": 18, + "milestone": "M2", + "executionMode": "AFK", + "labels": [ + "area:llama", + "area:weights", + "type:runtime", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "real-model", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-034/README.md", + "hardware": "optional", + "model": "dense-llama", + "upstream": "yes", + "dependsOn": [ + "DGR-028", + "DGR-029", + "DGR-031" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/034-implement-dense-llama-range-aware-gguf-ownership.md`, and evidence READMEs for dependencies (DGR-028, DGR-029, DGR-031) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Load only the dense-Llama tensors owned by a shard range.", + "acceptanceCriteria": [ + "Load only `blk.N.*` tensors in the assigned range, embeddings only at the head, and norm/output or tied output only at the tail.", + "Derive authoritative range and endpoint ownership from the loaded engine state.", + "Reject invalid/gapped/out-of-model ranges and unexpected required tensors.", + "Real-model evidence shows mapped/resident memory scales with owned tensors rather than full artifact size.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/034-implement-dense-llama-range-aware-gguf-ownership.md; prd.json is authoritative.", + "blocks": [ + "DGR-035", + "DGR-037", + "DGR-051" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-035", + "title": "Implement dense architecture boundary input/output", + "priority": 19, + "milestone": "M2", + "executionMode": "AFK", + "labels": [ + "area:llama", + "area:boundary", + "type:runtime", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "real-model", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-035/README.md", + "hardware": "optional", + "model": "dense-llama", + "upstream": "yes", + "dependsOn": [ + "DGR-021", + "DGR-031", + "DGR-034" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/035-implement-dense-architecture-boundary-input-output.md`, and evidence READMEs for dependencies (DGR-021, DGR-031, DGR-034) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Execute dense head/middle/tail ranges through an architecture-defined residual boundary.", + "acceptanceCriteria": [ + "Head accepts token IDs and owns embedding; middle/tail bypass embedding and accept a named boundary bundle.", + "Non-tail returns the unnormalized residual before final norm/head and before tail-only row pruning.", + "Tail returns logits or sampled-token output under an explicit contract.", + "Uncertified architectures and incompatible boundary schemas fail closed.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/035-implement-dense-architecture-boundary-input-output.md; prd.json is authoritative.", + "blocks": [ + "DGR-036", + "DGR-037", + "DGR-069" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-036", + "title": "Prove dense fixture and real-model range parity", + "priority": 20, + "milestone": "M2", + "executionMode": "AFK", + "labels": [ + "area:parity", + "area:testing", + "type:certification", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "real-model", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-036/README.md", + "hardware": "optional", + "model": "dense-llama", + "upstream": "yes", + "dependsOn": [ + "DGR-033", + "DGR-035" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/036-prove-dense-fixture-and-real-model-range-parity.md`, and evidence READMEs for dependencies (DGR-033, DGR-035) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Prove the engine/protocol seam before adding session concurrency.", + "acceptanceCriteria": [ + "Model-free two-stage tests pass through two fake worker processes with disjoint ranges.", + "A small real dense GGUF passes whole-model versus two-range prefill parity.", + "At least 32 greedy decode tokens match the locked tolerance.", + "Evidence distinguishes deterministic fixture proof from opt-in real-model proof.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/036-prove-dense-fixture-and-real-model-range-parity.md; prd.json is authoritative.", + "blocks": [ + "DGR-039" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-037", + "title": "Bind llama.cpp to the standalone worker", + "priority": 21, + "milestone": "M2", + "executionMode": "AFK", + "labels": [ + "area:worker", + "area:llama", + "type:vertical-slice", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "real-model", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-037/README.md", + "hardware": "optional", + "model": "dense-llama", + "upstream": "yes", + "dependsOn": [ + "DGR-022", + "DGR-023", + "DGR-031", + "DGR-034", + "DGR-035" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/037-bind-llama-cpp-to-the-standalone-worker.md`, and evidence READMEs for dependencies (DGR-022, DGR-023, DGR-031, DGR-034, DGR-035) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Replace the fake engine with the pinned llama.cpp `ShardEngine` implementation without changing the public worker contract.", + "acceptanceCriteria": [ + "Worker loads exactly one artifact/recipe/range identity and rejects mismatched stream requests.", + "All execution passes through `ShardEngine`; llama.cpp implementation types remain private.", + "Health and metrics expose loaded identity, authoritative ownership, memory, and execution state.", + "Graceful shutdown releases model/session resources; injected process death is observable and bounded.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/037-bind-llama-cpp-to-the-standalone-worker.md; prd.json is authoritative.", + "blocks": [ + "DGR-038", + "DGR-039", + "DGR-040", + "DGR-051" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-038", + "title": "Implement isolated shard-local Hot KV State", + "priority": 22, + "milestone": "M2", + "executionMode": "AFK", + "labels": [ + "area:kv-cache", + "area:concurrency", + "type:runtime", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "real-model", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-038/README.md", + "hardware": "optional", + "model": "dense-llama", + "upstream": "yes", + "dependsOn": [ + "DGR-037" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/038-implement-isolated-shard-local-hot-kv-state.md`, and evidence READMEs for dependencies (DGR-037) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Map each route session and epoch to isolated state containing only locally owned layers.", + "acceptanceCriteria": [ + "Map `(route_session_id, route_epoch)` to an isolated llama sequence or bounded context.", + "Support prefill/decode append, truncate, release, TTL/LRU eviction, cache miss, and stale-epoch rejection.", + "Four concurrent sessions complete without token, KV, position, or cancellation cross-talk.", + "Release/eviction returns memory to the configured budget without affecting other sessions.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/038-implement-isolated-shard-local-hot-kv-state.md; prd.json is authoritative.", + "blocks": [ + "DGR-039", + "DGR-052", + "DGR-055", + "DGR-069" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-039", + "title": "Pass local two-process dense acceptance", + "priority": 23, + "milestone": "M2", + "executionMode": "AFK", + "labels": [ + "area:integration", + "area:parity", + "type:certification", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "real-model", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-039/README.md", + "hardware": "optional", + "model": "dense-llama", + "upstream": "yes", + "dependsOn": [ + "DGR-036", + "DGR-037", + "DGR-038" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/039-pass-local-two-process-dense-acceptance.md`, and evidence READMEs for dependencies (DGR-036, DGR-037, DGR-038) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Establish the first real, independently executing distributed GGUF route on one host.", + "acceptanceCriteria": [ + "Two worker processes open disjoint dense ranges and both execute real prefill/decode work.", + "Whole-model parity, 32-token greedy decode, four-session isolation, cancellation, and cleanup pass.", + "Record TTFT, prefill/decode rates, seam bytes/latency, RSS/VRAM, KV, queue, and failure metrics.", + "Killing one worker returns a bounded structured failure rather than hanging.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/039-pass-local-two-process-dense-acceptance.md; prd.json is authoritative.", + "blocks": [ + "DGR-054" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-040", + "title": "Add node-side native worker supervision", + "priority": 24, + "milestone": "M2", + "executionMode": "AFK", + "labels": [ + "area:node", + "area:supervision", + "type:integration", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "fixture", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-040/README.md", + "hardware": "none", + "model": "generic", + "upstream": "no", + "dependsOn": [ + "DGR-033", + "DGR-037" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/040-add-node-side-native-worker-supervision.md`, and evidence READMEs for dependencies (DGR-033, DGR-037) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Let the existing node service safely start, probe, stop, and restart the standalone worker.", + "acceptanceCriteria": [ + "Supervision owns process startup, readiness, log capture, graceful shutdown, and bounded forced termination.", + "Startup verifies worker binary, artifact identity, recipe, and range before registration.", + "Crashes or health loss make the capability unavailable without corrupting the Transformers backend.", + "Tests use the fake worker and deterministic crash injection.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/040-add-node-side-native-worker-supervision.md; prd.json is authoritative.", + "blocks": [ + "DGR-041", + "DGR-042", + "DGR-055", + "DGR-058" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-041", + "title": "Register native Shard capabilities without redesigning Meshnet", + "priority": 25, + "milestone": "M2", + "executionMode": "AFK", + "labels": [ + "area:meshnet", + "area:admission", + "type:integration", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "model-free", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-041/README.md", + "hardware": "none", + "model": "generic", + "upstream": "no", + "dependsOn": [ + "DGR-025", + "DGR-040" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/041-register-native-shard-capabilities-without-redesigning-meshnet.md`, and evidence READMEs for dependencies (DGR-025, DGR-040) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Adapt native worker identity and capacity to existing backend-agnostic capability admission.", + "acceptanceCriteria": [ + "Registration carries exact recipe fingerprint, authoritative range, backend, memory/KV capacity, concurrency, and certification status.", + "Existing tracker, billing, routing, telemetry, and provider semantics remain backend-agnostic.", + "Uncertified backend/model/recipe combinations are visible but unroutable.", + "Existing Transformers registration and route tests remain unchanged in behavior.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/041-register-native-shard-capabilities-without-redesigning-meshnet.md; prd.json is authoritative.", + "blocks": [ + "DGR-043" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-042", + "title": "Carry native frames through direct and existing relay seams", + "priority": 26, + "milestone": "M2", + "executionMode": "AFK", + "labels": [ + "area:meshnet", + "area:relay", + "area:grpc", + "type:integration", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "fixture", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-042/README.md", + "hardware": "none", + "model": "generic", + "upstream": "no", + "dependsOn": [ + "DGR-024", + "DGR-040" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/042-carry-native-frames-through-direct-and-existing-relay-seams.md`, and evidence READMEs for dependencies (DGR-024, DGR-040) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Use direct gRPC where available and the existing relay as opaque protobuf transport without redesigning relay behavior.", + "acceptanceCriteria": [ + "Direct paths use the long-lived gRPC activation stream.", + "Relayed paths carry byte-identical versioned protobuf frames through the existing relay contract.", + "Request/work identity, cancellation, deadlines, telemetry, billing correlation, and per-node attribution survive both paths.", + "Fake-worker tests cover direct, relay, disconnect, cancellation, and bounded buffering.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/042-carry-native-frames-through-direct-and-existing-relay-seams.md; prd.json is authoritative.", + "blocks": [ + "DGR-054", + "DGR-058" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-043", + "title": "Expose GGUF compatibility and measured cost inputs to existing routing", + "priority": 27, + "milestone": "M2", + "executionMode": "AFK", + "labels": [ + "area:tracker", + "area:routing", + "type:integration", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "model-free", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-043/README.md", + "hardware": "none", + "model": "generic", + "upstream": "no", + "dependsOn": [ + "DGR-041" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/043-expose-gguf-compatibility-and-measured-cost-inputs-to-existing-routing.md`, and evidence READMEs for dependencies (DGR-041) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Adapt exact GGUF recipe/range compatibility and measured capacity, queue, seam-cost, health, and reliability data into the existing backend-agnostic routing inputs without redesigning routing or load balancing.", + "acceptanceCriteria": [ + "Expose exact recipe, range coverage, capacity, queue/load, seam-cost, health, reliability, backend, and certification measurements through existing tracker input contracts.", + "Prove existing routing forms complete compatible coverage and excludes dark or mismatched candidates using its current backend-agnostic mechanisms.", + "Regression-test unchanged Transformers behavior and unchanged tracker routing, load-balancing, billing, relay, and provider semantics.", + "Regression-test that no quant, stage count, fixed split, architecture, backend sequence, or DeepSeek-specific policy is hardcoded.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/043-expose-gguf-compatibility-and-measured-cost-inputs-to-existing-routing.md; prd.json is authoritative.", + "blocks": [ + "DGR-053", + "DGR-054", + "DGR-059", + "DGR-061" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-044", + "title": "Pin the DeepSeek V4 Flash target contract", + "priority": 28, + "milestone": "M3", + "executionMode": "AFK", + "labels": [ + "area:deepseek-v4", + "area:provenance", + "type:contract", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "model-free", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-044/README.md", + "hardware": "none", + "model": "deepseek-v4-flash", + "upstream": "yes", + "dependsOn": [ + "DGR-019", + "DGR-025", + "DGR-026", + "DGR-027" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/044-pin-the-deepseek-v4-flash-target-contract.md`, and evidence READMEs for dependencies (DGR-019, DGR-025, DGR-026, DGR-027) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Fix the alpha/beta model identity and upstream maturity assumptions before implementing the adapter.", + "acceptanceCriteria": [ + "Pin Hugging Face target SHA `60d8d70770c6776ff598c94bb586a859a38244f1`.", + "Record the selected GGUF provenance and exact source binding without assuming one quant.", + "Record that llama.cpp support began with PR 24162/commit `8c146a8` and remains maturing; the build manifest still pins one exact validated upstream commit.", + "Record 43 main layers plus MTP and all known architecture-specific state obligations.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/044-pin-the-deepseek-v4-flash-target-contract.md; prd.json is authoritative.", + "blocks": [ + "DGR-045" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-045", + "title": "Inventory V4 GGUF tensors and layer ownership", + "priority": 29, + "milestone": "M3", + "executionMode": "AFK", + "labels": [ + "area:deepseek-v4", + "area:weights", + "type:research-spike", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "real-model", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-045/README.md", + "hardware": "none", + "model": "deepseek-v4-flash", + "upstream": "yes", + "dependsOn": [ + "DGR-026", + "DGR-044" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/045-inventory-v4-gguf-tensors-and-layer-ownership.md`, and evidence READMEs for dependencies (DGR-026, DGR-044) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Derive exact head, repeated-layer, tail, expert, auxiliary-state, and MTP ownership from the pinned artifact.", + "acceptanceCriteria": [ + "Produce a machine-readable inventory tied to the target SHA and exact GGUF artifact.", + "Classify embeddings, 43 main layers, final head, MTP, mHC, attention variants, indexer/compressor, and MoE tensors.", + "Validate half-open range ownership and fail on unclassified required tensors.", + "Inventory tooling works across quants without embedding quant names in architecture logic.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/045-inventory-v4-gguf-tensors-and-layer-ownership.md; prd.json is authoritative.", + "blocks": [ + "DGR-046", + "DGR-047", + "DGR-050" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-046", + "title": "Define the V4 typed architecture boundary schema", + "priority": 30, + "milestone": "M3", + "executionMode": "AFK", + "labels": [ + "area:deepseek-v4", + "area:boundary", + "type:protocol", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "model-free", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-046/README.md", + "hardware": "none", + "model": "deepseek-v4-flash", + "upstream": "yes", + "dependsOn": [ + "DGR-021", + "DGR-045" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/046-define-the-v4-typed-architecture-boundary-schema.md`, and evidence READMEs for dependencies (DGR-021, DGR-045) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Define the exact cross-stage V4 architecture boundary while keeping per-layer attention and auxiliary caches shard-local.", + "acceptanceCriteria": [ + "Define a versioned named bundle for the mHC 4×4096 residual boundary, positions, token-ID sideband where required, and schema/cache expectations.", + "Explicitly exclude per-layer CSA, HCA, SWA, indexer, compressor, KV, and MTP caches/state from the WAN boundary; those remain local to the owning shard and session/epoch.", + "Reserve typed MTP boundary fields but mark MTP execution unsupported and unroutable for alpha.", + "Fingerprint independently of quant/topology and fail closed on missing, incompatible, incorrectly shaped, or stale boundary/cache expectations.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/046-define-the-v4-typed-architecture-boundary-schema.md; prd.json is authoritative.", + "blocks": [ + "DGR-047", + "DGR-048", + "DGR-049" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-047", + "title": "Adapt the upstream V4 mHC boundary for ranged ownership", + "priority": 31, + "milestone": "M3", + "executionMode": "AFK", + "labels": [ + "area:deepseek-v4", + "area:mhc", + "type:runtime", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "real-model", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-047/README.md", + "hardware": "optional", + "model": "deepseek-v4-flash", + "upstream": "yes", + "dependsOn": [ + "DGR-045", + "DGR-046" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/047-adapt-the-upstream-v4-mhc-boundary-for-ranged-ownership.md`, and evidence READMEs for dependencies (DGR-045, DGR-046) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Add range-boundary adapters around upstream llama.cpp V4 mHC execution without reimplementing the V4 graph or kernels.", + "acceptanceCriteria": [ + "Represent and validate the upstream V4 4×4096 mHC boundary without flattening semantic axes.", + "Add only head/intermediate/tail range ownership and boundary conversion hooks around the pinned upstream llama.cpp graph.", + "Compare deterministic fixture vectors and single-process ranged outputs with upstream whole-model execution.", + "Document that llama.cpp owns V4 mHC graph/kernels and that quantized storage does not alter the logical boundary schema.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/047-adapt-the-upstream-v4-mhc-boundary-for-ranged-ownership.md; prd.json is authoritative.", + "blocks": [ + "DGR-048", + "DGR-049", + "DGR-050", + "DGR-051" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-048", + "title": "Carry token-ID sideband through the first three hash-routed layers", + "priority": 32, + "milestone": "M3", + "executionMode": "AFK", + "labels": [ + "area:deepseek-v4", + "area:routing-state", + "type:runtime", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "real-model", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-048/README.md", + "hardware": "optional", + "model": "deepseek-v4-flash", + "upstream": "yes", + "dependsOn": [ + "DGR-046", + "DGR-047" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/048-carry-token-id-sideband-through-the-first-three-hash-routed-layers.md`, and evidence READMEs for dependencies (DGR-046, DGR-047) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Ensure any stage containing the first three hash-routed layers receives exact token identities.", + "acceptanceCriteria": [ + "Head emits token IDs in the typed sideband for boundaries that require them.", + "Intermediate stages preserve or consume the sideband according to their layer range.", + "Routes splitting before, within, and after the first three layers pass deterministic partition tests.", + "Missing or mismatched token IDs fail closed rather than silently selecting incorrect experts.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/048-carry-token-id-sideband-through-the-first-three-hash-routed-layers.md; prd.json is authoritative.", + "blocks": [ + "DGR-051" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-049", + "title": "Keep V4 attention and auxiliary state shard-local", + "priority": 33, + "milestone": "M3", + "executionMode": "AFK", + "labels": [ + "area:deepseek-v4", + "area:attention", + "type:runtime", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "real-model", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-049/README.md", + "hardware": "optional", + "model": "deepseek-v4-flash", + "upstream": "yes", + "dependsOn": [ + "DGR-046", + "DGR-047" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/049-keep-v4-attention-and-auxiliary-state-shard-local.md`, and evidence READMEs for dependencies (DGR-046, DGR-047) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Bind V4 CSA/HCA/SWA/indexer/compressor and KV state to the owning shard session/epoch rather than transferring caches over the WAN.", + "acceptanceCriteria": [ + "Map CSA, HCA, SWA, indexer, compressor, and KV ownership from the pinned upstream graph to each owned layer range.", + "Key all such caches/state by route session and epoch with bounded lifecycle, memory accounting, stale-epoch rejection, release, and eviction.", + "Prove cross-stage messages carry only the typed architecture boundary and cache expectations, never per-layer cache contents.", + "On route change or state loss, use explicit cache miss and re-prefill/restart; do not migrate V4 caches across workers.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/049-keep-v4-attention-and-auxiliary-state-shard-local.md; prd.json is authoritative.", + "blocks": [ + "DGR-051" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-050", + "title": "Validate upstream V4 MoE and hash-routing execution under ranged ownership", + "priority": 34, + "milestone": "M3", + "executionMode": "AFK", + "labels": [ + "area:deepseek-v4", + "area:moe", + "type:runtime", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "real-model", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-050/README.md", + "hardware": "optional", + "model": "deepseek-v4-flash", + "upstream": "yes", + "dependsOn": [ + "DGR-045", + "DGR-047" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/050-validate-upstream-v4-moe-and-hash-routing-execution-under-ranged-ownership.md`, and evidence READMEs for dependencies (DGR-045, DGR-047) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Validate the pinned upstream llama.cpp V4 MoE and hash-routing graph when layers are range-owned, without reimplementing routing or expert kernels in Meshnet.", + "acceptanceCriteria": [ + "Load range-owned tensors for 256 routed plus one shared expert and validate upstream execution activates six routed experts where specified.", + "Validate the first three upstream hash-routed layers receive exact token-ID sideband across splits before, within, and after them.", + "Compare upstream whole-model and ranged router/expert outputs, shared-expert contribution, and malformed sideband failures.", + "Document that llama.cpp owns V4 MoE, attention, hash routing, graph, and kernels; no expert-parallel WAN collective or Meshnet reimplementation is introduced.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/050-validate-upstream-v4-moe-and-hash-routing-execution-under-ranged-ownership.md; prd.json is authoritative.", + "blocks": [ + "DGR-051" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-051", + "title": "Assemble the DeepSeek V4 Flash `ShardEngine` adapter", + "priority": 35, + "milestone": "M3", + "executionMode": "AFK", + "labels": [ + "area:deepseek-v4", + "area:engine", + "type:vertical-slice", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "real-model", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-051/README.md", + "hardware": "optional", + "model": "deepseek-v4-flash", + "upstream": "yes", + "dependsOn": [ + "DGR-034", + "DGR-037", + "DGR-047", + "DGR-048", + "DGR-049", + "DGR-050" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/051-assemble-the-deepseek-v4-flash-shardengine-adapter.md`, and evidence READMEs for dependencies (DGR-034, DGR-037, DGR-047, DGR-048, DGR-049, DGR-050) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Assemble range ownership hooks and boundary/local-state adapters around upstream llama.cpp V4 execution behind the stable ShardEngine interface.", + "acceptanceCriteria": [ + "Support valid head, middle, tail, and whole-model ranges over all 43 main layers using the pinned upstream llama.cpp V4 graph/kernels.", + "Integrate exact range ownership, mHC boundary, positions, required token-ID sideband, and shard-local session/epoch state adapters.", + "Report MTP reserved-but-not-executable for alpha and reject unsupported split points or cache expectations.", + "Include exact adapter/schema/runtime/artifact identity and valid split restrictions without reimplementing V4 MoE, attention, mHC, or hash routing.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/051-assemble-the-deepseek-v4-flash-shardengine-adapter.md; prd.json is authoritative.", + "blocks": [ + "DGR-052", + "DGR-060", + "DGR-065", + "DGR-069" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-052", + "title": "Pass local V4 whole-model versus ranged parity", + "priority": 36, + "milestone": "M3", + "executionMode": "AFK", + "labels": [ + "area:deepseek-v4", + "area:parity", + "type:certification", + "priority:p0", + "ready-for-agent" + ], + "evidenceClass": "real-model", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-052/README.md", + "hardware": "optional", + "model": "deepseek-v4-flash", + "upstream": "yes", + "dependsOn": [ + "DGR-038", + "DGR-051" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/052-pass-local-v4-whole-model-versus-ranged-parity.md`, and evidence READMEs for dependencies (DGR-038, DGR-051) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Prove V4 prefill and decode correctness locally before network certification.", + "acceptanceCriteria": [ + "Compare pinned whole-model llama.cpp with at least two valid ranged partitions.", + "Prefill intermediates and locked-length greedy decode pass architecture-specific tolerances.", + "Test splits around the first three hash-routed layers and at least one CSA/HCA/SWA/indexer/compressor transition.", + "Four concurrent sessions pass KV/state isolation and cleanup.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/052-pass-local-v4-whole-model-versus-ranged-parity.md; prd.json is authoritative.", + "blocks": [ + "DGR-053", + "DGR-054" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-053", + "title": "Certify a real 2–4-stage V4 route", + "priority": 37, + "milestone": "M3", + "executionMode": "HITL", + "labels": [ + "area:deepseek-v4", + "area:hardware", + "type:certification", + "priority:p0", + "gate:hitl", + "ready-for-human" + ], + "evidenceClass": "real-hardware", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-053/README.md", + "hardware": "required", + "model": "deepseek-v4-flash", + "upstream": "yes", + "dependsOn": [ + "DGR-030", + "DGR-043", + "DGR-052" + ], + "triage": "ready-for-human", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/053-certify-a-real-2-4-stage-v4-route.md`, and evidence READMEs for dependencies (DGR-030, DGR-043, DGR-052) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Prove real Tracker-selected V4 execution across physical machines before alpha.", + "acceptanceCriteria": [ + "Run one documented 2–4-stage certification scenario using exact compatible artifacts/recipes; the count and chosen quant are evidence inputs, not product constants.", + "Actual CPU/GPU work executes on every stage; fake workers do not satisfy acceptance.", + "Record parity, TTFT, prefill/decode speed, seam cost, memory, cache/state isolation, cancellation, and cleanup.", + "Tracker selection remains dynamic and rejects an injected incompatible backend/recipe.", + "Only the exact real-hardware lanes exercised become eligible for advertisement.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/053-certify-a-real-2-4-stage-v4-route.md; prd.json is authoritative.", + "blocks": [ + "DGR-054", + "DGR-062", + "DGR-067" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-054", + "title": "Enforce the DeepSeek V4 Flash alpha gate", + "priority": 38, + "milestone": "M3", + "executionMode": "HITL", + "labels": [ + "area:deepseek-v4", + "area:release", + "milestone:alpha", + "priority:p0", + "gate:hitl", + "ready-for-human" + ], + "evidenceClass": "release", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-054/README.md", + "hardware": "required", + "model": "deepseek-v4-flash", + "upstream": "yes", + "dependsOn": [ + "DGR-017", + "DGR-019", + "DGR-020", + "DGR-039", + "DGR-042", + "DGR-043", + "DGR-052", + "DGR-053" + ], + "triage": "ready-for-human", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/054-enforce-the-deepseek-v4-flash-alpha-gate.md`, and evidence READMEs for dependencies (DGR-017, DGR-019, DGR-020, DGR-039, DGR-042, DGR-043, DGR-052, DGR-053) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Release alpha only when V4 is correct and clears the pre-locked useful-speed requirement.", + "acceptanceCriteria": [ + "Evaluate correctness, model fit, TTFT, prefill/decode speed, seam cost, memory, and failure rate against DGF-004 without changing thresholds.", + "Separate quant/model-fit gains from runtime/transport gains.", + "Decision is `alpha`, `optimize measured bottleneck`, or `stop`; failures cannot be relabeled as certification.", + "Alpha documentation states MTP is reserved but not implemented and identifies every dark hardware lane.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/054-enforce-the-deepseek-v4-flash-alpha-gate.md; prd.json is authoritative.", + "blocks": [ + "DGR-055", + "DGR-065", + "DGR-066", + "DGR-068" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-055", + "title": "Implement compatible continuous decode batching", + "priority": 39, + "milestone": "M4", + "executionMode": "AFK", + "labels": [ + "area:scheduler", + "area:batching", + "type:performance", + "priority:p1", + "ready-for-agent" + ], + "evidenceClass": "fixture", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-055/README.md", + "hardware": "none", + "model": "generic", + "upstream": "no", + "dependsOn": [ + "DGR-038", + "DGR-040", + "DGR-054" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/055-implement-compatible-continuous-decode-batching.md`, and evidence READMEs for dependencies (DGR-038, DGR-040, DGR-054) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Batch compatible active sessions without violating route, recipe, position, or architecture state.", + "acceptanceCriteria": [ + "Batch only sessions with compatible engine, recipe, phase, boundary schema, and state layout.", + "Preserve per-session positions, sequence IDs, outputs, cancellation, and accounting.", + "Decode receives bounded service while prefill remains schedulable.", + "Deterministic 1/2/4/8 concurrency tests show no cross-session corruption.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/055-implement-compatible-continuous-decode-batching.md; prd.json is authoritative.", + "blocks": [ + "DGR-056", + "DGR-057" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-056", + "title": "Enforce bounded admission, queues, and backpressure", + "priority": 40, + "milestone": "M4", + "executionMode": "AFK", + "labels": [ + "area:scheduler", + "area:backpressure", + "type:performance", + "priority:p1", + "ready-for-agent" + ], + "evidenceClass": "fixture", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-056/README.md", + "hardware": "none", + "model": "generic", + "upstream": "no", + "dependsOn": [ + "DGR-055" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/056-enforce-bounded-admission-queues-and-backpressure.md`, and evidence READMEs for dependencies (DGR-055) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Prevent weight, KV, state, scratch, and stream buffers from exceeding admitted capacity.", + "acceptanceCriteria": [ + "Admission accounts separately for weights, KV/state, scratch, in-flight fragments, and queue slots.", + "Queue and stream limits produce structured retryable or terminal responses.", + "Prefill cannot starve decode and one route session cannot monopolize queue capacity.", + "Telemetry reports active sessions, queue depth/time, batch occupancy, memory pressure, and rejects.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/056-enforce-bounded-admission-queues-and-backpressure.md; prd.json is authoritative.", + "blocks": [ + "DGR-057", + "DGR-058", + "DGR-060" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-057", + "title": "Benchmark batching saturation and fairness", + "priority": 41, + "milestone": "M4", + "executionMode": "AFK", + "labels": [ + "area:performance", + "area:batching", + "type:benchmark", + "priority:p1", + "ready-for-agent" + ], + "evidenceClass": "real-hardware", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-057/README.md", + "hardware": "required", + "model": "dense-llama+deepseek-v4", + "upstream": "no", + "dependsOn": [ + "DGR-055", + "DGR-056" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/057-benchmark-batching-saturation-and-fairness.md`, and evidence READMEs for dependencies (DGR-055, DGR-056) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Identify useful concurrency and saturation points without assuming one global batch size.", + "acceptanceCriteria": [ + "Run controlled concurrency 1/2/4/8 and record aggregate throughput, per-request p50/p95, TTFT, queue time, occupancy, and memory.", + "Measure dense and V4 lanes separately where hardware permits.", + "Verify bounded fairness and no prefill/decode starvation.", + "Produce machine-readable saturation recommendations consumed by capability reporting, not hardcoded constants.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/057-benchmark-batching-saturation-and-fairness.md; prd.json is authoritative.", + "blocks": [ + "DGR-061", + "DGR-063", + "DGR-070" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-058", + "title": "Harden worker and stream failure semantics", + "priority": 42, + "milestone": "M4", + "executionMode": "AFK", + "labels": [ + "area:reliability", + "area:failure", + "type:hardening", + "priority:p1", + "ready-for-agent" + ], + "evidenceClass": "fixture", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-058/README.md", + "hardware": "none", + "model": "generic", + "upstream": "no", + "dependsOn": [ + "DGR-040", + "DGR-042", + "DGR-056" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/058-harden-worker-and-stream-failure-semantics.md`, and evidence READMEs for dependencies (DGR-040, DGR-042, DGR-056) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Ensure malformed input, process death, transport reset, and cancellation terminate cleanly.", + "acceptanceCriteria": [ + "Test worker death, stream reset, malformed bundle, checksum failure, deadline, cache miss, stale epoch, and partial fragment loss.", + "Cancellation propagates across all stages and releases KV/state, queue entries, and fragment buffers.", + "Duplicate steps are idempotent; uncertain mutations are never silently replayed.", + "Billing/work outcomes distinguish completed, cancelled, failed, and unverified work.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/058-harden-worker-and-stream-failure-semantics.md; prd.json is authoritative.", + "blocks": [ + "DGR-059", + "DGR-060", + "DGR-061" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-059", + "title": "Implement alpha-safe route recovery", + "priority": 43, + "milestone": "M4", + "executionMode": "AFK", + "labels": [ + "area:recovery", + "area:routing", + "type:hardening", + "priority:p1", + "ready-for-agent" + ], + "evidenceClass": "fixture", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-059/README.md", + "hardware": "none", + "model": "generic", + "upstream": "no", + "dependsOn": [ + "DGR-043", + "DGR-058" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/059-implement-alpha-safe-route-recovery.md`, and evidence READMEs for dependencies (DGR-043, DGR-058) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Recover from route loss without importing or continuing unverified state.", + "acceptanceCriteria": [ + "On route loss or local-state cache miss, restart from token zero or re-prefill on a newly compatible route according to the locked alpha contract.", + "Never import KV, CSA, HCA, SWA, indexer, compressor, recurrent, or MTP cache/state across workers.", + "Keep exact same-route duplicate delivery idempotent while cross-route continuation fails closed.", + "Test direct/relay loss, cache miss, replacement selection, client cancellation, and billing reconciliation.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/059-implement-alpha-safe-route-recovery.md; prd.json is authoritative.", + "blocks": [ + "DGR-070" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-060", + "title": "Certify V4 long-context state correctness", + "priority": 44, + "milestone": "M4", + "executionMode": "AFK", + "labels": [ + "area:deepseek-v4", + "area:long-context", + "type:certification", + "priority:p1", + "ready-for-agent" + ], + "evidenceClass": "real-hardware", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-060/README.md", + "hardware": "required", + "model": "deepseek-v4-flash", + "upstream": "yes", + "dependsOn": [ + "DGR-051", + "DGR-056", + "DGR-058" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/060-certify-v4-long-context-state-correctness.md`, and evidence READMEs for dependencies (DGR-051, DGR-056, DGR-058) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Prove V4’s KV and auxiliary state remain correct and bounded at long contexts.", + "acceptanceCriteria": [ + "Exercise pre-locked context lengths covering multiple prefill chunks and sustained decode.", + "Validate KV plus CSA/HCA/SWA/indexer/compressor state positions across every stage.", + "Measure memory growth, fragment sizes, TTFT, decode degradation, cancellation latency, and cleanup.", + "Cache mismatch, truncation, and context-limit behavior fail deterministically.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/060-certify-v4-long-context-state-correctness.md; prd.json is authoritative.", + "blocks": [ + "DGR-062", + "DGR-064", + "DGR-065", + "DGR-066", + "DGR-070" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-061", + "title": "Certify existing routing with 10+ GGUF stage candidates", + "priority": 45, + "milestone": "M4", + "executionMode": "AFK", + "labels": [ + "area:tracker", + "area:scale", + "type:simulation", + "priority:p1", + "ready-for-agent" + ], + "evidenceClass": "fixture", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-061/README.md", + "hardware": "none", + "model": "generic", + "upstream": "no", + "dependsOn": [ + "DGR-043", + "DGR-057", + "DGR-058" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/061-certify-existing-routing-with-10-gguf-stage-candidates.md`, and evidence READMEs for dependencies (DGR-043, DGR-057, DGR-058) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Certify that existing backend-agnostic routing consumes GGUF compatibility and measured-cost inputs for a 10+ candidate scenario without algorithm or policy redesign.", + "acceptanceCriteria": [ + "Generate deterministic pools with 10+ compatible GGUF stage candidates plus slower, overloaded, unhealthy, and incompatible alternatives.", + "Run the existing routing implementation unchanged and verify complete coverage, compatibility, acyclicity, and use of measured inputs.", + "Regression-test that no stage count, quant, fixed split, architecture, or backend sequence is encoded in production routing policy.", + "Verify existing route recomputation reacts to measured load/failure while tracker, load-balancing, billing, relay, and provider semantics remain unchanged.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/061-certify-existing-routing-with-10-gguf-stage-candidates.md; prd.json is authoritative.", + "blocks": [ + "DGR-062", + "DGR-063" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-062", + "title": "Certify a dynamic real 10+ stage V4 scenario", + "priority": 46, + "milestone": "M4", + "executionMode": "HITL", + "labels": [ + "area:deepseek-v4", + "area:scale", + "area:hardware", + "type:certification", + "priority:p1", + "gate:hitl", + "ready-for-human" + ], + "evidenceClass": "real-hardware", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-062/README.md", + "hardware": "required", + "model": "deepseek-v4-flash", + "upstream": "yes", + "dependsOn": [ + "DGR-053", + "DGR-060", + "DGR-061" + ], + "triage": "ready-for-human", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/062-certify-a-dynamic-real-10-stage-v4-scenario.md`, and evidence READMEs for dependencies (DGR-053, DGR-060, DGR-061) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Demonstrate that a large real route can be dynamically selected and usefully execute V4.", + "acceptanceCriteria": [ + "Run one real 10+-stage V4 certification scenario; stage count, quant, and split remain scenario metadata only.", + "Every selected stage proves real work, exact compatible identity, local state ownership, and bounded resources.", + "Record end-to-end and per-stage TTFT, prefill/decode, seam cost, queueing, memory, failures, and cleanup.", + "Inject at least one incompatible or degraded candidate and verify dynamic exclusion/reselection.", + "The scenario must meet its pre-locked usefulness threshold or remain failed evidence.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/062-certify-a-dynamic-real-10-stage-v4-scenario.md; prd.json is authoritative.", + "blocks": [ + "DGR-067", + "DGR-070" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-063", + "title": "Profile and optimize the critical seam", + "priority": 47, + "milestone": "M4", + "executionMode": "AFK", + "labels": [ + "area:performance", + "type:optimization", + "priority:p1", + "ready-for-agent" + ], + "evidenceClass": "real-hardware", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-063/README.md", + "hardware": "required", + "model": "generic", + "upstream": "conditional", + "dependsOn": [ + "DGR-057", + "DGR-061" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/063-profile-and-optimize-the-critical-seam.md`, and evidence READMEs for dependencies (DGR-057, DGR-061) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Optimize only the measured dominant compute, serialization, copy, or transport bottleneck.", + "acceptanceCriteria": [ + "Profile worker compute, tensor conversion, copies, protobuf framing, compression, relay/direct transport, queueing, and synchronization.", + "Select one dominant bottleneck from evidence and lock its before/after benchmark.", + "Implement one bounded optimization without weakening correctness or protocol identity.", + "Report whether the optimization changes TTFT, prefill, decode, throughput, or memory and preserve raw data.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/063-profile-and-optimize-the-critical-seam.md; prd.json is authoritative.", + "blocks": [ + "DGR-064" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-064", + "title": "Add negotiated activation compression", + "priority": 48, + "milestone": "M4", + "executionMode": "AFK", + "labels": [ + "area:protocol", + "area:compression", + "type:optimization", + "priority:p1", + "ready-for-agent" + ], + "evidenceClass": "real-hardware", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-064/README.md", + "hardware": "required", + "model": "deepseek-v4-flash", + "upstream": "no", + "dependsOn": [ + "DGR-060", + "DGR-063" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/064-add-negotiated-activation-compression.md`, and evidence READMEs for dependencies (DGR-060, DGR-063) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Reduce V4 seam cost only when a certified compression recipe improves end-to-end performance acceptably.", + "acceptanceCriteria": [ + "Negotiate compression through recipe identity; unnegotiated or mismatched compression fails closed.", + "Preserve names, shapes, semantic axes, token-ID sideband, and checksums.", + "Measure quality drift, encode/decode cost, bytes, TTFT, and throughput against uncompressed boundaries.", + "Compression remains dark unless it meets pre-locked quality and speed thresholds.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/064-add-negotiated-activation-compression.md; prd.json is authoritative.", + "blocks": [ + "DGR-066", + "DGR-070" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-065", + "title": "Define V4 MTP ownership and distributed state contract", + "priority": 49, + "milestone": "M4", + "executionMode": "AFK", + "labels": [ + "area:deepseek-v4", + "area:mtp", + "type:contract", + "priority:p1", + "ready-for-agent" + ], + "evidenceClass": "fixture", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-065/README.md", + "hardware": "none", + "model": "deepseek-v4-flash", + "upstream": "yes", + "dependsOn": [ + "DGR-051", + "DGR-054", + "DGR-060" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/065-define-v4-mtp-ownership-and-distributed-state-contract.md`, and evidence READMEs for dependencies (DGR-051, DGR-054, DGR-060) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Lock MTP tensor, execution, boundary, acceptance/rejection, and session-state ownership before implementation while keeping MTP disabled for alpha.", + "acceptanceCriteria": [ + "Derive exact MTP tensor and execution ownership from the pinned V4 target and upstream llama.cpp graph, distinguishing main-layer, tail, and MTP responsibilities.", + "Define typed MTP inputs/outputs plus accepted-token, rejection, rollback/truncation, position, cache, and session/epoch lifecycle semantics.", + "Specify which MTP state remains shard-local and which typed boundary values cross a seam; prohibit WAN migration of KV or V4 auxiliary caches.", + "Keep every MTP recipe disabled and unroutable for alpha, with fail-closed capability negotiation and deterministic contract fixtures.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/065-define-v4-mtp-ownership-and-distributed-state-contract.md; prd.json is authoritative.", + "blocks": [ + "DGR-066" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-066", + "title": "Implement and benchmark V4 MTP", + "priority": 50, + "milestone": "M4", + "executionMode": "AFK", + "labels": [ + "area:deepseek-v4", + "area:mtp", + "type:runtime", + "priority:p1", + "ready-for-agent" + ], + "evidenceClass": "real-hardware", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-066/README.md", + "hardware": "required", + "model": "deepseek-v4-flash", + "upstream": "yes", + "dependsOn": [ + "DGR-054", + "DGR-060", + "DGR-064", + "DGR-065" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/066-implement-and-benchmark-v4-mtp.md`, and evidence READMEs for dependencies (DGR-054, DGR-060, DGR-064, DGR-065) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Implement the locked MTP contract around upstream llama.cpp before beta, without making MTP an alpha prerequisite.", + "acceptanceCriteria": [ + "Implement the exact DGR-065 MTP ownership and typed state contract against the pinned upstream V4 graph while preserving shard-local caches.", + "Pass whole-model versus ranged MTP correctness, accepted-token, rejection, rollback/truncation, and session-isolation tests.", + "Benchmark MTP-off versus MTP-on quality, accepted-token rate, TTFT, decode speed, seam bytes, and memory on the locked lane.", + "Distinguish implemented, certified, disabled, and unsupported MTP recipes in fail-closed capability advertisement.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/066-implement-and-benchmark-v4-mtp.md; prd.json is authoritative.", + "blocks": [ + "DGR-067", + "DGR-070" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-067", + "title": "Certify the backend capability matrix", + "priority": 51, + "milestone": "M4", + "executionMode": "HITL", + "labels": [ + "area:hardware", + "area:admission", + "type:certification", + "priority:p1", + "gate:hitl", + "ready-for-human" + ], + "evidenceClass": "real-hardware", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-067/README.md", + "hardware": "required", + "model": "deepseek-v4-flash", + "upstream": "yes", + "dependsOn": [ + "DGR-030", + "DGR-053", + "DGR-062", + "DGR-066" + ], + "triage": "ready-for-human", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/067-certify-the-backend-capability-matrix.md`, and evidence READMEs for dependencies (DGR-030, DGR-053, DGR-062, DGR-066) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Publish only backend/model/recipe lanes proven on actual CPU, CUDA, ROCm, Vulkan, or Metal hardware.", + "acceptanceCriteria": [ + "Maintain independent build and certification status for CPU, CUDA, ROCm, Vulkan, and Metal.", + "Each advertised lane includes real hardware/driver/runtime/model evidence for parity, concurrency, cancellation, cleanup, and useful speed.", + "Build success alone never makes a lane routable; unavailable hardware remains explicitly dark.", + "Tracker admission consumes signed/versioned certification records rather than backend-name allowlists.", + "Mixed-backend routes require exact compatibility evidence and fail closed otherwise.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/067-certify-the-backend-capability-matrix.md; prd.json is authoritative.", + "blocks": [ + "DGR-068", + "DGR-070" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-068", + "title": "Package reproducible native worker releases", + "priority": 52, + "milestone": "M5", + "executionMode": "AFK", + "labels": [ + "area:packaging", + "area:release", + "type:delivery", + "priority:p1", + "ready-for-agent" + ], + "evidenceClass": "release", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-068/README.md", + "hardware": "optional", + "model": "generic", + "upstream": "yes", + "dependsOn": [ + "DGR-030", + "DGR-054", + "DGR-067" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/068-package-reproducible-native-worker-releases.md`, and evidence READMEs for dependencies (DGR-030, DGR-054, DGR-067) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Produce installable worker packages that preserve exact source, patch, protocol, and certification identity.", + "acceptanceCriteria": [ + "Package worker binaries/configuration for supported host/backend combinations without bundling an unverified llama.cpp tree.", + "Embed protocol, engine, upstream pin, patch-stack, build-toolchain, and certification fingerprints.", + "Installation/startup refuses mismatched artifacts, runtime recipes, or unsupported hardware lanes.", + "Produce checksums, SBOM/license attribution, reproducible build instructions, and smoke tests.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/068-package-reproducible-native-worker-releases.md; prd.json is authoritative.", + "blocks": [ + "DGR-070" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-069", + "title": "Prepare narrow upstream llama.cpp collaboration patches", + "priority": 53, + "milestone": "M5", + "executionMode": "HITL", + "labels": [ + "area:upstream", + "area:patches", + "type:collaboration", + "priority:p2", + "gate:hitl", + "ready-for-human" + ], + "evidenceClass": "release", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-069/README.md", + "hardware": "none", + "model": "generic+deepseek-v4", + "upstream": "yes", + "dependsOn": [ + "DGR-028", + "DGR-035", + "DGR-038", + "DGR-051" + ], + "triage": "ready-for-human", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/069-prepare-narrow-upstream-llama-cpp-collaboration-patches.md`, and evidence READMEs for dependencies (DGR-028, DGR-035, DGR-038, DGR-051) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Reduce long-term patch burden through generic upstreamable hooks without asking llama.cpp to own Meshnet.", + "acceptanceCriteria": [ + "Separate generic range loading, boundary I/O, and filtered state hooks from project worker/protocol code.", + "Provide one scoped patch, focused test, and minimal reproducer per concern against the exact upstream pin.", + "Compare the proposal with prior-art evidence and current upstream V4 support/maturity.", + "Prepare human-ready design/outreach text; actual issue/PR submission remains a human action.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/069-prepare-narrow-upstream-llama-cpp-collaboration-patches.md; prd.json is authoritative.", + "blocks": [ + "DGR-071" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-070", + "title": "Enforce the DeepSeek V4 Flash beta gate", + "priority": 54, + "milestone": "M5", + "executionMode": "HITL", + "labels": [ + "area:deepseek-v4", + "area:release", + "milestone:beta", + "priority:p0", + "gate:hitl", + "ready-for-human" + ], + "evidenceClass": "release", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-070/README.md", + "hardware": "required", + "model": "deepseek-v4-flash", + "upstream": "yes", + "dependsOn": [ + "DGR-057", + "DGR-059", + "DGR-060", + "DGR-062", + "DGR-064", + "DGR-066", + "DGR-067", + "DGR-068" + ], + "triage": "ready-for-human", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/070-enforce-the-deepseek-v4-flash-beta-gate.md`, and evidence READMEs for dependencies (DGR-057, DGR-059, DGR-060, DGR-062, DGR-064, DGR-066, DGR-067, DGR-068) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Promote beta only after concurrency, resilience, long-context, MTP, scale, packaging, and speed gates pass.", + "acceptanceCriteria": [ + "Evaluate all beta metrics against DGF-004 without changing thresholds after observing results.", + "Require V4 parity, batching/fairness, bounded backpressure, failure recovery, long-context correctness, MTP evidence, and dynamic 10+ stage evidence.", + "Publish the exact certified hardware/backend/recipe matrix; all other lanes remain dark.", + "Decision is `beta`, `targeted optimization`, or `stop/rollback`, with unresolved failures listed explicitly.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/070-enforce-the-deepseek-v4-flash-beta-gate.md; prd.json is authoritative.", + "blocks": [ + "DGR-071" + ], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + }, + { + "id": "DGR-071", + "title": "Establish upstream pin, patch, and certification maintenance", + "priority": 55, + "milestone": "M5", + "executionMode": "AFK", + "labels": [ + "area:maintenance", + "area:upstream", + "area:certification", + "type:operations", + "priority:p2", + "ready-for-agent" + ], + "evidenceClass": "release", + "evidencePath": ".scratch/distributed-gguf-runtime/evidence/DGR-071/README.md", + "hardware": "optional", + "model": "deepseek-v4-flash", + "upstream": "yes", + "dependsOn": [ + "DGR-069", + "DGR-070" + ], + "triage": "ready-for-agent", + "description": "Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/071-establish-upstream-pin-patch-and-certification-maintenance.md`, and evidence READMEs for dependencies (DGR-069, DGR-070) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Keep beta reproducible and detect upstream/model/hardware drift before it reaches routable nodes.", + "acceptanceCriteria": [ + "Add a documented update procedure for llama.cpp pin, numbered patches, protocol/engine versions, V4 target revision, and certification records.", + "A candidate pin update must apply/build/test in isolation and cannot replace the production pin automatically.", + "Any changed graph, tensor inventory, boundary, cache/state layout, backend behavior, or performance invalidates affected certification.", + "Add scheduled model-free checks plus opt-in real-hardware recertification instructions and rollback procedure.", + "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." + ], + "passes": true, + "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/071-establish-upstream-pin-patch-and-certification-maintenance.md; prd.json is authoritative.", + "blocks": [], + "completionNotes": "Ephemeral controller masking; canonical PRD remains authoritative." + } + ], + "metadata": { + "updatedAt": "2026-07-25T19:38:00.109Z", + "controller_ephemeral": true, + "controller_story": "DGR-033" + } +} \ No newline at end of file diff --git a/.scratch/distributed-gguf-runtime/evidence/DGR-033/README.md b/.scratch/distributed-gguf-runtime/evidence/DGR-033/README.md new file mode 100644 index 0000000..8b8408a --- /dev/null +++ b/.scratch/distributed-gguf-runtime/evidence/DGR-033/README.md @@ -0,0 +1,208 @@ +# DGR-033 evidence — standalone fake C++ gRPC Shard worker + +**Completed:** 2026-07-25 +**Branch:** `ralph/distributed-gguf-opus` +**Authority:** `.scratch/distributed-gguf-runtime/prd.json` +**Dependencies:** DGR-022 (lifecycle/status contract), DGR-024 (real generated +gRPC harness + `shard_runtime_server.py` reference semantics), DGR-032 +(deterministic fake `ShardEngine` semantics). + +## Objective + +Prove the standalone worker process, stream, lifecycle, and supervision shape +before any llama.cpp integration: a real C++ executable that serves the whole +ShardRuntime lifecycle/stream contract over gRPC using a model-free fake engine, +driven end-to-end by Python integration tests over a real socket. + +## What was found live before changing code + +- `packages/node/native/proto/shard_runtime.proto` (DGR-021..023): the single + semantic contract. Its `ShardRuntime` service has exactly five RPCs — + `GetCapability`, `Health`, `Session` (bidi stream), `Release`, `Cancel`. +- `packages/node/meshnet_node/shard_runtime_server.py` (DGR-024): the reference + Python servicer. It performs a *bounded real forward* (a CRC over the received + bundle bytes) then echoes the chunk, and fails closed on stale epoch, expired + deadline, corrupt/mis-tiled fragments, exhausted flow-control credit, duplicate + idempotency step, and in-band/out-of-band cancellation, with per-`route_session_id` + state kept on the servicer so an out-of-band `Cancel` can reach a live session. + **Key finding:** despite the schema labelling the checksum `CRC32C`, this + runtime computes it with `zlib.crc32` (standard CRC-32, *not* Castagnoli). The + C++ worker mirrors `zlib.crc32` exactly so its checksum acceptance is + byte-identical to the existing Python surface (the committed C++ *conformance* + test, by contrast, uses true Castagnoli against separately-generated goldens — + the two are unrelated code paths). +- `packages/node/native/CMakeLists.txt` (DGR-029/030): configures against the + ignored `build/native-toolchain` prefix (pinned Protobuf 33.1 + gRPC 1.82.1), + always generates both message and service stubs, and registers a C++ + conformance CTest. There was **no** worker executable and **no** Python + worker integration test before this story (confirmed by + `ls packages/node/native/worker` → absent, and grep for `shard_worker`). +- `packages/node/meshnet_node/fake_shard_engine.py` (DGR-032): the Python fake + engine, deliberately *not* wired into the gRPC surface. DGR-033's worker is + its native analogue — a separate executable, not a consumer of that module — + so both fakes present identical behaviour to a client (deterministic, + model-free bounded forward; per-session isolation; fail-closed lifecycle). + +## What was added (this story's change) + +### `packages/node/native/worker/fake_engine.h` (new) + +`meshnet::worker::FakeShardEngine` — a header-only, model-free fixture engine. +Its only capability is to validate a `TensorBundle` (fragments tile exactly, the +uncompressed CRC-32 matches the declared checksum, the declared payload stays +within the negotiated `max_chunk_bytes`) and fold the fragment bytes through a +bounded forward. It links, loads, and dispatches to **nothing** — no llama.cpp, +no graph execution. Carries `kEvidenceClass = "fixture"` mirroring the Python +`FakeShardEngine.EVIDENCE_CLASS` for the later DGR-036 parity check. + +### `packages/node/native/worker/shard_service.{h,cpp}` (new) + +`ShardRuntimeServiceImpl : meshnet::shard::v1::ShardRuntime::Service` — a faithful +C++ port of the DGR-024 Python servicer: the same per-`route_session_id` +identity/credit/dedup state guarded by a mutex, the same fail-closed negative +paths, and the same lifecycle (open → prefill/decode → flow-control top-up → +release/cancel). Each per-request response is computed under the lock and written +*after* releasing it, so a blocking `Write` can never deadlock the out-of-band +`Cancel` RPC that needs the same lock. Bounded messages are enforced two ways: a +per-tensor `RESOURCE_EXHAUSTED` app check against `max_chunk_bytes`, plus a hard +transport receive ceiling. + +### `packages/node/native/worker/shard_worker_main.cpp` (new) + +The standalone `shard_worker` executable. Binds `MESHNET_SHARD_LISTEN_ADDR` +(or an `argv` address), prints one readiness line (`ShardRuntime worker listening +on `), and serves until `SIGTERM`/`SIGINT`. **Graceful shutdown** uses a +self-pipe: the async-signal-safe handler writes one byte, a drain thread reads it +and calls `server->Shutdown()`, so in-flight sessions finish and the process +exits `0` printing `ShardRuntime worker shut down cleanly`. A `--selftest` mode +binds an ephemeral port and self-drives capability/health/fragmented-prefill/ +decode/release over a real loopback gRPC channel, giving a pure-C++ CTest that +needs no Python. + +### `packages/node/native/CMakeLists.txt` (modified) + +Adds the `shard_worker` executable (linking only `shard_runtime_grpc` + +`gRPC::grpc++` — no llama.cpp) and registers `shard_worker_selftest` as a CTest. + +### `tests/test_native_shard_worker.py` (new) + +18 integration tests that spawn the **real compiled binary** as a subprocess and +drive it with the committed generated stubs over a real localhost socket. When +the binary is not built they skip (the DGR-029/030 `requires_cmake` gating +pattern), locating it via `MESHNET_SHARD_WORKER_BIN` or `build/native/shard_worker`. + +## Acceptance criteria → evidence + +1. **Standalone C++ executable serves the complete lifecycle/stream contract + using the fake engine** — `shard_worker` builds and serves all five RPCs; the + `shard_worker_selftest` CTest drives open → fragmented prefill → decode → + release over real gRPC; the 18 Python tests cover the same against the + subprocess. +2. **Python integration tests cover startup, health, capability, fragmented + prefill, decode, release, cancellation, graceful shutdown** — + `test_worker_startup_and_health`, `test_worker_capability`, + `test_fragmented_prefill_echoes_reassembled_payload` (3-fragment tiling), + `test_decode_step_is_served`, `test_release_is_terminal`, + `test_in_band_cancel_of_single_work_item_does_not_end_stream`, + `test_in_band_cancel_of_whole_session_is_terminal`, + `test_out_of_band_cancel_rpc_races_ahead_of_open`, + `test_graceful_shutdown_on_sigterm` (SIGTERM → exit 0 + clean-shutdown line). +3. **Bounded messages, deadlines, flow control, independent session + cancellation enforced** — `test_bounded_message_is_rejected` + (`RESOURCE_EXHAUSTED` on an over-ceiling tensor), + `test_expired_deadline_is_rejected`, `test_flow_control_violation_and_topup`, + `test_independent_session_cancellation` (cancelling session A leaves session B + fully serviceable), plus `test_stale_route_epoch_is_rejected`, + `test_duplicate_idempotency_step_is_acked`, + `test_malformed_fragment_tiling_is_rejected`. +4. **Exposes neither llama.cpp RPC nor arbitrary graph execution** — + `ldd build/native/shard_worker` shows no llama/ggml shared libs; + `nm -C build/native/shard_worker | grep -icE 'llama_|ggml_'` → `0`; the proto + exposes exactly one service with five lifecycle RPCs and no graph-exec entry. +5. **Gates + this handoff** — below. + +## Commands and results + +Toolchain (ignored `build/native-toolchain`, pinned Protobuf 33.1 + gRPC 1.82.1): + +```bash +bash scripts/bootstrap_native_toolchain.sh "$PWD/build/native-toolchain" +# ... gRPC 1.82.1 commit acccf84c0df20487d64101f528e5d426541ca4e5 +# grpc_cpp_plugin sha256 43705cf26ae9ce98bbcee76b3408f5e171eec746b50bf0dd42dd68d132c6a533 +``` + +Focused out-of-tree CMake build + CTest: + +```bash +cmake -S packages/node/native -B build/native -DCMAKE_PREFIX_PATH="$PWD/build/native-toolchain" +cmake --build build/native -j"$(nproc)" +ctest --test-dir build/native --output-on-failure +``` +```text +1/2 Test #1: shard_worker_selftest ............ Passed 0.01 sec +2/2 Test #2: shard_protocol_conformance ....... Passed 0.00 sec +100% tests passed out of 2 +``` + +Python integration tests against the real binary: + +```bash +PYTHONPATH=packages/node:packages/tracker python -m pytest -q tests/test_native_shard_worker.py +``` +```text +18 passed in 3.96s +``` + +AC4 (no llama.cpp / no graph exec): + +```bash +ldd build/native/shard_worker | grep -iE 'llama|ggml' # -> (no matches) +nm build/native/shard_worker | grep -icE 'llama_|ggml_' # -> 0 +``` + +Shared gates + regression: + +```bash +python -m compileall -q packages tests # exit 0 +git diff --check -- packages/node/native tests/test_native_shard_worker.py # exit 0 +PYTHONPATH=packages/node:packages/tracker python -m pytest -q \ + tests/test_shard_runtime_harness.py tests/test_native_shard_protocol.py +# -> 61 passed, 2 skipped (DGR-024 harness + native protocol untouched) +``` + +Toolchain used: `cmake`/`ctest` from the `distributed-gguf-runtime` worktree's +`.venv` (PyPI `cmake==4.4.0` wheel — no system cmake exists here, same as +DGR-029/030); the Python client uses that venv's `grpcio==1.82.1`, +`grpcio-tools==1.82.1`, `protobuf`, `pytest`. `g++ (GCC) 15.2.1`. + +## Limitations + +- This is FIXTURE evidence only. The worker's "forward" is a CRC-over-wire-bytes + echo, not real tensor compute; it proves process/stream/lifecycle/supervision + shape, nothing about numerical correctness. Real engine binding is DGR-037 and + numeric parity is DGR-036/052. +- The worker checksum path mirrors the DGR-024 runtime's `zlib.crc32` (standard + CRC-32 under a `CRC32C` label). Compressed-tensor tiling/checksum is not + independently verified (no zstd decompressor in the fixture) — identical to the + DGR-024 limitation. +- Default `pytest` runs skip `tests/test_native_shard_worker.py` unless the + worker binary is built (or `MESHNET_SHARD_WORKER_BIN` is set); this session + built it and ran all 18 for real (results above). Building requires the pinned + gRPC C++ toolchain, which is not present by default and must be bootstrapped. +- No CUDA/ROCm/GPU, no model download, no network at test time — all default + tests are fixture-only and offline. + +## Dependency handoff + +- **DGR-036** (fixture vs real-model parity): the worker's `FakeShardEngine` + carries `kEvidenceClass = "fixture"`; diff it against DGR-037's real engine's + equivalent marker, and reuse the same lifecycle/stream contract this worker + serves to prove behavioural parity before numeric parity. +- **DGR-037** (bind llama.cpp): replace `FakeShardEngine`'s bounded forward with + the real engine behind the *same* `ShardRuntimeServiceImpl` surface; the + service's session/epoch/credit/dedup/cancel machinery and the graceful-shutdown + supervision shape are reusable as-is. +- **DGR-040** (worker supervision): `shard_worker` already provides the + supervision primitives — a readiness line for start detection, `SIGTERM` + graceful drain with a clean-exit line, and a `--selftest` liveness probe. + A supervisor can start/monitor/restart the process around these. 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 7ce3989..8f506fd 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:** specification only; `ready-for-agent`; `passes: false` +- **Status / triage:** completed; `passes: true` - **Execution mode:** `AFK` - **Milestone:** `M1` - **Dependencies:** `DGR-022`, `DGR-024`, `DGR-032` @@ -18,11 +18,11 @@ Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, ## Acceptance criteria -- [ ] A standalone C++ executable serves the complete lifecycle and stream RPC contract using the fake engine. -- [ ] Python integration tests cover startup, health, capability, fragmented prefill, decode, release, cancellation, and graceful shutdown. -- [ ] Bounded messages, deadlines, flow control, and independent session cancellation are enforced. -- [ ] The worker exposes neither llama.cpp RPC nor arbitrary graph execution. -- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff. +- [x] A standalone C++ executable serves the complete lifecycle and stream RPC contract using the fake engine. +- [x] Python integration tests cover startup, health, capability, fragmented prefill, decode, release, cancellation, and graceful shutdown. +- [x] Bounded messages, deadlines, flow control, and independent session cancellation are enforced. +- [x] The worker exposes neither llama.cpp RPC nor arbitrary graph execution. +- [x] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff. ## Shared quality gates @@ -30,10 +30,7 @@ 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 -Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-033/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit. +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 d065c3b..af372c9 100644 --- a/.scratch/distributed-gguf-runtime/prd.json +++ b/.scratch/distributed-gguf-runtime/prd.json @@ -656,12 +656,13 @@ "The worker exposes neither llama.cpp RPC nor arbitrary graph execution.", "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff." ], - "passes": false, + "passes": true, "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/033-build-a-standalone-fake-c-grpc-shard-worker.md; prd.json is authoritative.", "blocks": [ "DGR-036", "DGR-040" - ] + ], + "completionNotes": "Completed by agent" }, { "id": "DGR-034", diff --git a/packages/node/native/CMakeLists.txt b/packages/node/native/CMakeLists.txt index 5622929..7e0faac 100644 --- a/packages/node/native/CMakeLists.txt +++ b/packages/node/native/CMakeLists.txt @@ -62,6 +62,21 @@ message(STATUS "Pinned gRPC ${gRPC_VERSION}: building ShardRuntime service stubs enable_testing() +# The standalone fake Shard worker (DGR-033): a real gRPC server over the +# ShardRuntime service, backed by the model-free FakeShardEngine. It links the +# grpc service stubs only — no llama.cpp, no graph-execution entry point. +add_executable(shard_worker + worker/shard_worker_main.cpp + worker/shard_service.cpp) +target_include_directories(shard_worker PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/worker") +target_link_libraries(shard_worker PRIVATE shard_runtime_grpc gRPC::grpc++) + +# Pure-C++ CTest: the worker binds an ephemeral port, self-drives the full +# lifecycle (capability, health, fragmented prefill, decode, release) over a +# real loopback gRPC channel, and exits non-zero on any mismatch. This proves +# the worker serves the contract without needing a Python environment. +add_test(NAME shard_worker_selftest COMMAND shard_worker --selftest) + add_executable(shard_protocol_conformance tests/test_shard_protocol_conformance.cpp) target_link_libraries(shard_protocol_conformance PRIVATE shard_runtime_proto) diff --git a/packages/node/native/worker/fake_engine.h b/packages/node/native/worker/fake_engine.h new file mode 100644 index 0000000..6da4b38 --- /dev/null +++ b/packages/node/native/worker/fake_engine.h @@ -0,0 +1,164 @@ +// Deterministic, model-free fake ShardEngine for the native worker (DGR-033). +// +// This is the C++ analogue of `meshnet_node.fake_shard_engine.FakeShardEngine` +// (DGR-032): a pure fixture that performs a *bounded real forward* over the +// bytes it received off the socket and never links, loads, or dispatches to +// llama.cpp. It exists to prove the standalone worker process, stream, +// lifecycle, and supervision shape before any real engine is bound (DGR-037). +// +// The "forward" is deliberately transport-verifiable rather than semantic: it +// reassembles a tensor's fragments, checks they tile exactly, and derives a +// CRC32C over the uncompressed bytes — the same rule the schema's `Checksum` +// declares and the same bounded forward the DGR-024 Python surface performs. +// Feeding the same bytes back (echo) lets a client prove the payload truly +// traversed the wire and returned unmodified; a direct hop and an opaque relay +// of the identical frames therefore yield byte-identical responses. +// +// There is no arbitrary-graph entry point here and no llama.cpp RPC: the engine +// only knows how to reassemble/checksum a bundle. That is the whole point of a +// fixture worker (acceptance criterion 4). + +#ifndef MESHNET_NATIVE_WORKER_FAKE_ENGINE_H_ +#define MESHNET_NATIVE_WORKER_FAKE_ENGINE_H_ + +#include +#include +#include +#include +#include + +#include "shard_runtime.pb.h" + +namespace meshnet::worker { + +namespace sp = ::meshnet::shard::v1; + +// Standard CRC-32 (ISO-HDLC / zlib polynomial 0xEDB88320, reflected). +// +// The schema's `Checksum` field is labelled CRC32C, but the DGR-024 Python +// runtime surface (`shard_runtime_server.py`) computes it with `zlib.crc32` +// (standard CRC-32, not the Castagnoli CRC32C). This worker deliberately mirrors +// that exact computation so its checksum acceptance is byte-for-byte identical +// to the existing Python gRPC surface and to a relayed frame's expectations. +inline uint32_t Crc32(const std::string& data, uint32_t seed = 0) { + static uint32_t table[256]; + static bool built = false; + if (!built) { + for (uint32_t i = 0; i < 256; ++i) { + uint32_t c = i; + for (int k = 0; k < 8; ++k) { + c = (c & 1) ? (c >> 1) ^ 0xEDB88320u : (c >> 1); + } + table[i] = c; + } + built = true; + } + uint32_t crc = seed ^ 0xFFFFFFFFu; + for (unsigned char byte : data) { + crc = (crc >> 8) ^ table[(crc ^ byte) & 0xFF]; + } + return crc ^ 0xFFFFFFFFu; +} + +// Outcome of validating one bundle before the bounded forward runs. +struct BundleCheck { + // Set when the bundle is malformed/corrupt (maps to PAYLOAD_CORRUPT). + std::optional corrupt_detail; + // Set when the declared payload exceeds the negotiated per-chunk ceiling + // (maps to RESOURCE_EXHAUSTED) — the worker refuses unbounded messages. + std::optional oversize_detail; +}; + +// The fake engine's only capability: verify a bundle tiles and checksums, and +// that it stays within the negotiated byte ceiling. Mirrors `_validate_bundle` +// in `shard_runtime_server.py` plus the bounded-message rule DGR-033 adds. +class FakeShardEngine { + public: + // Marker mirroring `FakeShardEngine.EVIDENCE_CLASS` so a future parity check + // (DGR-036) can assert this is a fixture, not a real engine. + static constexpr const char* kEvidenceClass = "fixture"; + + explicit FakeShardEngine(uint64_t max_chunk_bytes) : max_chunk_bytes_(max_chunk_bytes) {} + + BundleCheck Validate(const sp::TensorBundle& bundle) const { + BundleCheck result; + for (const auto& tensor : bundle.tensors()) { + // Bounded message: a declared payload larger than the ceiling is refused + // before any reassembly work is done. + if (max_chunk_bytes_ != 0 && tensor.total_bytes() > max_chunk_bytes_) { + result.oversize_detail = + "tensor '" + tensor.name() + "': declared total_bytes " + + std::to_string(tensor.total_bytes()) + " exceeds max_chunk_bytes " + + std::to_string(max_chunk_bytes_); + return result; + } + + // Fragments must tile the wire body exactly: no hole, no overlap. + std::vector ordered; + ordered.reserve(tensor.fragments_size()); + for (const auto& fragment : tensor.fragments()) { + ordered.push_back(&fragment); + } + std::sort(ordered.begin(), ordered.end(), + [](const sp::TensorFragment* a, const sp::TensorFragment* b) { + return a->byte_offset() < b->byte_offset(); + }); + uint64_t expected_offset = 0; + std::string payload; + for (const auto* fragment : ordered) { + if (fragment->byte_offset() != expected_offset) { + result.corrupt_detail = + "tensor '" + tensor.name() + "': fragment at offset " + + std::to_string(fragment->byte_offset()) + + " does not tile the preceding " + std::to_string(expected_offset) + + " bytes (gap or overlap)"; + return result; + } + payload.append(fragment->payload()); + expected_offset += fragment->payload().size(); + } + if (tensor.compression() == sp::COMPRESSION_NONE && + expected_offset != tensor.total_bytes()) { + result.corrupt_detail = + "tensor '" + tensor.name() + "': fragments cover " + + std::to_string(expected_offset) + " bytes, declared total_bytes is " + + std::to_string(tensor.total_bytes()); + return result; + } + if (tensor.compression() == sp::COMPRESSION_NONE && + tensor.checksum().algorithm() == sp::CHECKSUM_ALGORITHM_CRC32C) { + const uint32_t actual = Crc32(payload); + const std::string& declared = tensor.checksum().value(); + std::string actual_be(4, '\0'); + actual_be[0] = static_cast((actual >> 24) & 0xFF); + actual_be[1] = static_cast((actual >> 16) & 0xFF); + actual_be[2] = static_cast((actual >> 8) & 0xFF); + actual_be[3] = static_cast(actual & 0xFF); + if (declared != actual_be) { + result.corrupt_detail = "tensor '" + tensor.name() + "': checksum mismatch"; + return result; + } + } + } + return result; + } + + // Bounded real forward: fold every fragment's payload through CRC32C so the + // digest is only reproducible if the payload really traversed the wire. + uint32_t BoundedForward(const sp::TensorBundle& bundle) const { + uint32_t digest = 0; + for (const auto& tensor : bundle.tensors()) { + for (const auto& fragment : tensor.fragments()) { + digest = Crc32(fragment.payload(), digest); + } + } + return digest; + } + + private: + uint64_t max_chunk_bytes_; +}; + +} // namespace meshnet::worker + +#endif // MESHNET_NATIVE_WORKER_FAKE_ENGINE_H_ diff --git a/packages/node/native/worker/shard_service.cpp b/packages/node/native/worker/shard_service.cpp new file mode 100644 index 0000000..d72c295 --- /dev/null +++ b/packages/node/native/worker/shard_service.cpp @@ -0,0 +1,364 @@ +#include "shard_service.h" + +#include +#include + +namespace meshnet::worker { + +namespace { + +int64_t NowUnixNanos() { + return std::chrono::duration_cast( + std::chrono::system_clock::now().time_since_epoch()) + .count(); +} + +// Build the standard fail response (a terminal-or-not ShardStatus). +sp::SessionResponse MakeFail(const std::string& route_session_id, const std::string& work_id, + uint64_t step, sp::ErrorCode code, const std::string& detail, + bool terminal, bool retryable) { + sp::SessionResponse response; + sp::ShardStatus* status = response.mutable_status(); + status->set_work_id(work_id); + status->set_route_session_id(route_session_id); + status->set_idempotency_step(step); + status->set_terminal(terminal); + sp::ShardError* error = status->mutable_error(); + error->set_code(code); + error->set_detail(detail); + error->set_retryable(retryable); + return response; +} + +sp::SessionResponse MakeAck(const std::string& work_id, uint64_t step, bool duplicate) { + sp::SessionResponse response; + sp::Ack* ack = response.mutable_ack(); + ack->set_work_id(work_id); + ack->set_idempotency_step(step); + ack->set_duplicate(duplicate); + return response; +} + +void FillDefaultFlow(sp::FlowControl* fc, const FlowLimits& limits) { + fc->set_credits_granted(limits.credits_granted); + fc->set_max_inflight_chunks(limits.max_inflight_chunks); + fc->set_max_chunk_bytes(limits.max_chunk_bytes); + fc->set_max_prefill_chunk_tokens(limits.max_prefill_chunk_tokens); +} + +} // namespace + +grpc::Status ShardRuntimeServiceImpl::GetCapability(grpc::ServerContext*, + const sp::CapabilityRequest*, + sp::CapabilityReport* response) { + response->set_schema_version(sp::SCHEMA_VERSION_1); + sp::Fingerprint* fp = response->mutable_fingerprint(); + fp->set_model_artifact_digest("sha256:native-test-artifact"); + fp->set_runtime_recipe_digest("sha256:native-test-recipe"); + fp->set_recipe_id("native-test"); + fp->set_recipe_version("1"); + fp->set_catalogue_version("1"); + sp::ShardRange* range = response->mutable_shard_range(); + range->set_start_layer(0); + range->set_end_layer(32); + range->set_effective_start_layer(0); + response->set_backend("grpc-native-cpp"); + response->set_device("cpu"); + response->set_validated(true); + response->set_detail("bounded real forward passed for fixture artifact"); + response->set_max_concurrent_sessions(8); + response->set_max_context_tokens(131072); + FillDefaultFlow(response->mutable_flow_control(), limits_); + response->add_accepted_compression(sp::COMPRESSION_NONE); + response->add_supported_schema_versions(sp::SCHEMA_VERSION_1); + response->set_validated_at_unix_nanos(0); + return grpc::Status::OK; +} + +grpc::Status ShardRuntimeServiceImpl::Health(grpc::ServerContext*, const sp::HealthRequest*, + sp::HealthReport* response) { + response->set_schema_version(sp::SCHEMA_VERSION_1); + response->set_state(sp::SERVING_STATE_SERVING); + response->set_active_sessions(1); + response->set_queued_chunks(0); + response->set_batch_occupancy(0); + response->set_kv_pressure(0.0f); + response->set_resident_bytes(0); + response->set_detail("native fixture worker serving"); + return grpc::Status::OK; +} + +uint32_t ShardRuntimeServiceImpl::MarkCancelled(const std::string& route_session_id, + const std::string& work_id) { + std::lock_guard lk(sessions_mu_); + SessionState& state = sessions_[route_session_id]; // creates on first cancel-before-open + if (state.max_inflight == 0) { + // Freshly created placeholder for a Cancel that raced ahead of Open. + state.credits = limits_.credits_granted; + state.max_inflight = limits_.max_inflight_chunks; + state.max_chunk_bytes = limits_.max_chunk_bytes; + } + if (work_id.empty()) { + const bool already = state.cancelled_session; + state.cancelled_session = true; + return already ? 0 : 1; + } + const bool already = state.cancelled_work.count(work_id) != 0; + state.cancelled_work.insert(work_id); + return already ? 0 : 1; +} + +grpc::Status ShardRuntimeServiceImpl::Session( + grpc::ServerContext*, + grpc::ServerReaderWriter* stream) { + std::string route_session_id; + sp::SessionRequest request; + + while (stream->Read(&request)) { + switch (request.kind_case()) { + case sp::SessionRequest::kOpen: { + const sp::SessionOpen& open = request.open(); + route_session_id = open.route_session_id(); + { + std::lock_guard lk(sessions_mu_); + SessionState state; + state.epoch = open.route_epoch(); + if (open.has_proposed_flow_control()) { + const sp::FlowControl& fc = open.proposed_flow_control(); + state.credits = fc.credits_granted(); + state.max_inflight = fc.max_inflight_chunks(); + state.max_chunk_bytes = fc.max_chunk_bytes(); + } else { + state.credits = limits_.credits_granted; + state.max_inflight = limits_.max_inflight_chunks; + state.max_chunk_bytes = limits_.max_chunk_bytes; + } + auto it = sessions_.find(route_session_id); + if (it != sessions_.end()) { + // A prior out-of-band Cancel may have marked this session cancelled + // before Open arrived; preserve that so the work still fails closed. + state.cancelled_session = it->second.cancelled_session; + state.cancelled_work = it->second.cancelled_work; + } + sessions_[route_session_id] = std::move(state); + } + sp::SessionResponse response; + sp::SessionAccepted* accepted = response.mutable_accepted(); + accepted->set_schema_version(sp::SCHEMA_VERSION_1); + accepted->set_route_session_id(open.route_session_id()); + accepted->set_route_epoch(open.route_epoch()); + if (open.has_proposed_flow_control()) { + *accepted->mutable_flow_control() = open.proposed_flow_control(); + } else { + FillDefaultFlow(accepted->mutable_flow_control(), limits_); + } + if (open.accepted_compression_size() > 0) { + for (int c : open.accepted_compression()) { + accepted->add_accepted_compression(static_cast(c)); + } + } else { + accepted->add_accepted_compression(sp::COMPRESSION_NONE); + } + *accepted->mutable_fingerprint() = open.fingerprint(); + stream->Write(response); + break; + } + + case sp::SessionRequest::kChunk: { + const sp::ActivationChunk& chunk = request.chunk(); + const sp::Envelope& envelope = chunk.envelope(); + const std::string work_id = envelope.work_id(); + const uint64_t step = envelope.idempotency_step(); + + // Compute the response under the lock, then write it *after* releasing — + // holding the lock across a (possibly blocking) Write would deadlock an + // out-of-band Cancel RPC that needs the same lock. + sp::SessionResponse response; + { + std::lock_guard lk(sessions_mu_); + auto it = sessions_.find(route_session_id); + SessionState* state = it != sessions_.end() ? &it->second : nullptr; + + if (state && (state->cancelled_session || state->cancelled_work.count(work_id))) { + response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_CANCELLED, + "work was cancelled", false, false); + } else if (state && envelope.route_epoch() < state->epoch) { + response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_EPOCH_STALE, + "stale route epoch", false, false); + } else if (envelope.deadline_unix_nanos() != 0 && + NowUnixNanos() > envelope.deadline_unix_nanos()) { + response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_DEADLINE_EXCEEDED, + "deadline already passed", false, false); + } else if (state && state->seen_steps.count(step)) { + response = MakeAck(work_id, step, /*duplicate=*/true); + } else if (state && state->credits <= 0) { + response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_FLOW_CONTROL_VIOLATION, + "no flow-control credit remaining", false, true); + } else { + const BundleCheck check = engine_.Validate(chunk.bundle()); + if (check.oversize_detail) { + response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_RESOURCE_EXHAUSTED, + *check.oversize_detail, false, false); + } else if (check.corrupt_detail) { + response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_PAYLOAD_CORRUPT, + *check.corrupt_detail, false, false); + } else { + if (state) { + state->seen_steps.insert(step); + state->credits -= 1; + } + engine_.BoundedForward(chunk.bundle()); // real bounded forward over wire bytes + *response.mutable_chunk() = chunk; // echo the exact bundle back + } + } + } + stream->Write(response); + break; + } + + case sp::SessionRequest::kDecode: { + const sp::DecodeStep& step_msg = request.decode(); + const std::string work_id = step_msg.work_id(); + const uint64_t step = step_msg.idempotency_step(); + + sp::TensorBundle bundle; + if (step_msg.bundle().tensors_size() > 0) { + bundle = step_msg.bundle(); + } else { + bundle.set_bundle_version(1); + *bundle.add_tensors() = step_msg.tensor(); + } + + sp::SessionResponse response; + { + std::lock_guard lk(sessions_mu_); + auto it = sessions_.find(route_session_id); + SessionState* state = it != sessions_.end() ? &it->second : nullptr; + + if (state && (state->cancelled_session || state->cancelled_work.count(work_id))) { + response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_CANCELLED, + "work was cancelled", false, false); + } else if (step_msg.deadline_unix_nanos() != 0 && + NowUnixNanos() > step_msg.deadline_unix_nanos()) { + response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_DEADLINE_EXCEEDED, + "deadline already passed", false, false); + } else if (state && state->seen_steps.count(step)) { + response = MakeAck(work_id, step, /*duplicate=*/true); + } else if (state && state->credits <= 0) { + response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_FLOW_CONTROL_VIOLATION, + "no flow-control credit remaining", false, true); + } else { + const BundleCheck check = engine_.Validate(bundle); + if (check.oversize_detail) { + response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_RESOURCE_EXHAUSTED, + *check.oversize_detail, false, false); + } else if (check.corrupt_detail) { + response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_PAYLOAD_CORRUPT, + *check.corrupt_detail, false, false); + } else { + if (state) { + state->seen_steps.insert(step); + state->credits -= 1; + } + engine_.BoundedForward(bundle); + // No decode response field exists; echo the step back as a + // chunk-bearing SessionResponse per the proto's relayed-frame design. + sp::ActivationChunk* out = response.mutable_chunk(); + sp::Envelope* out_env = out->mutable_envelope(); + out_env->set_schema_version(sp::SCHEMA_VERSION_1); + out_env->set_work_id(work_id); + out_env->set_idempotency_step(step); + out_env->set_phase(sp::PHASE_DECODE); + sp::PositionSpan* pos = out_env->mutable_position(); + pos->set_first_position(step_msg.position()); + pos->set_token_count(1); + *out->mutable_bundle() = bundle; + } + } + } + stream->Write(response); + break; + } + + case sp::SessionRequest::kFlowControl: { + const uint32_t topup = request.flow_control().credits_granted(); + sp::SessionResponse response; + { + std::lock_guard lk(sessions_mu_); + auto it = sessions_.find(route_session_id); + sp::FlowControl* fc = response.mutable_flow_control(); + if (it != sessions_.end()) { + SessionState& state = it->second; + int64_t granted = std::min(state.credits + topup, + static_cast(state.max_inflight)); + state.credits = granted; + fc->set_credits_granted(static_cast(granted)); + fc->set_max_inflight_chunks(state.max_inflight); + fc->set_max_chunk_bytes(state.max_chunk_bytes); + } else { + fc->set_credits_granted(topup != 0 ? topup : limits_.credits_granted); + fc->set_max_inflight_chunks(limits_.max_inflight_chunks); + fc->set_max_chunk_bytes(limits_.max_chunk_bytes); + } + fc->set_max_prefill_chunk_tokens(limits_.max_prefill_chunk_tokens); + } + stream->Write(response); + break; + } + + case sp::SessionRequest::kRelease: { + const sp::ReleaseSignal& release = request.release(); + sp::SessionResponse response; + sp::ShardStatus* status = response.mutable_status(); + status->set_work_id(release.work_id()); + status->set_route_session_id(release.route_session_id()); + status->set_terminal(true); + stream->Write(response); + return grpc::Status::OK; + } + + case sp::SessionRequest::kCancel: { + const sp::CancelSignal& signal = request.cancel(); + MarkCancelled(route_session_id, signal.work_id()); + const bool whole_session = signal.work_id().empty(); + stream->Write(MakeFail(route_session_id, signal.work_id(), 0, sp::ERROR_CODE_CANCELLED, + signal.reason().empty() ? "cancelled" : signal.reason(), + whole_session, false)); + if (whole_session) { + return grpc::Status::OK; + } + break; + } + + default: { + sp::SessionResponse response; + response.mutable_status()->set_terminal(true); + stream->Write(response); + return grpc::Status::OK; + } + } + } + return grpc::Status::OK; +} + +grpc::Status ShardRuntimeServiceImpl::Release(grpc::ServerContext*, + const sp::ReleaseRequest* request, + sp::ReleaseResponse* response) { + bool existed; + { + std::lock_guard lk(sessions_mu_); + existed = sessions_.erase(request->route_session_id()) != 0; + } + response->set_released(existed); + return grpc::Status::OK; +} + +grpc::Status ShardRuntimeServiceImpl::Cancel(grpc::ServerContext*, + const sp::CancelRequest* request, + sp::CancelResponse* response) { + const uint32_t newly = MarkCancelled(request->route_session_id(), request->work_id()); + response->set_cancelled_work_items(newly); + return grpc::Status::OK; +} + +} // namespace meshnet::worker diff --git a/packages/node/native/worker/shard_service.h b/packages/node/native/worker/shard_service.h new file mode 100644 index 0000000..a53cfad --- /dev/null +++ b/packages/node/native/worker/shard_service.h @@ -0,0 +1,85 @@ +// The native Shard worker's ShardRuntime service (DGR-033). +// +// A faithful C++ port of `ShardRuntimeServicer` in `shard_runtime_server.py`: +// the same per-`route_session_id` identity/credit/dedup state, the same +// fail-closed negative paths (stale epoch, expired deadline, corrupt/oversize +// payload, exhausted flow-control credit, duplicate idempotency step, in-band +// and out-of-band cancellation), and the same lifecycle (open/prefill/decode/ +// flow-control/release/cancel). The only compute it does is the fake engine's +// bounded forward — there is no llama.cpp linkage and no arbitrary-graph RPC. + +#ifndef MESHNET_NATIVE_WORKER_SHARD_SERVICE_H_ +#define MESHNET_NATIVE_WORKER_SHARD_SERVICE_H_ + +#include +#include +#include +#include +#include + +#include + +#include "fake_engine.h" +#include "shard_runtime.grpc.pb.h" +#include "shard_runtime.pb.h" + +namespace meshnet::worker { + +namespace sp = ::meshnet::shard::v1; + +struct FlowLimits { + uint32_t credits_granted = 16; + uint32_t max_inflight_chunks = 16; + uint64_t max_chunk_bytes = 4u * 1024u * 1024u; + uint32_t max_prefill_chunk_tokens = 512; +}; + +// Per-route-session identity/credit/dedup state, kept on the servicer instance +// (guarded by a lock) so an out-of-band unary Cancel from a different handler +// thread can reach a session a concurrent Session stream is still iterating. +struct SessionState { + uint64_t epoch = 0; + int64_t credits = 0; + uint32_t max_inflight = 0; + uint64_t max_chunk_bytes = 0; + std::set seen_steps; + std::set cancelled_work; + bool cancelled_session = false; +}; + +class ShardRuntimeServiceImpl final : public sp::ShardRuntime::Service { + public: + explicit ShardRuntimeServiceImpl(FlowLimits limits) + : limits_(limits), engine_(limits.max_chunk_bytes) {} + + grpc::Status GetCapability(grpc::ServerContext* context, + const sp::CapabilityRequest* request, + sp::CapabilityReport* response) override; + + grpc::Status Health(grpc::ServerContext* context, const sp::HealthRequest* request, + sp::HealthReport* response) override; + + grpc::Status Session( + grpc::ServerContext* context, + grpc::ServerReaderWriter* stream) override; + + grpc::Status Release(grpc::ServerContext* context, const sp::ReleaseRequest* request, + sp::ReleaseResponse* response) override; + + grpc::Status Cancel(grpc::ServerContext* context, const sp::CancelRequest* request, + sp::CancelResponse* response) override; + + private: + // Returns the number of items newly marked cancelled, creating session state + // if the Cancel raced ahead of SessionOpen. + uint32_t MarkCancelled(const std::string& route_session_id, const std::string& work_id); + + FlowLimits limits_; + FakeShardEngine engine_; + std::mutex sessions_mu_; + std::map sessions_; +}; + +} // namespace meshnet::worker + +#endif // MESHNET_NATIVE_WORKER_SHARD_SERVICE_H_ diff --git a/packages/node/native/worker/shard_worker_main.cpp b/packages/node/native/worker/shard_worker_main.cpp new file mode 100644 index 0000000..8b48686 --- /dev/null +++ b/packages/node/native/worker/shard_worker_main.cpp @@ -0,0 +1,302 @@ +// Standalone native Shard worker executable (DGR-033). +// +// Serves the complete ShardRuntime lifecycle/stream contract over real +// gRPC/HTTP2 using the model-free FakeShardEngine. It links neither llama.cpp +// nor any graph-execution entry point: the only surface it exposes is the +// ShardRuntime service defined in shard_runtime.proto. +// +// Usage: +// shard_worker [listen_addr] serve until SIGTERM/SIGINT (graceful drain) +// shard_worker --selftest bind an ephemeral port, self-drive the +// lifecycle over a real loopback channel, exit +// +// Environment: +// MESHNET_SHARD_LISTEN_ADDR host:port to bind (default localhost:50051) +// MESHNET_MAX_CHUNK_BYTES per-chunk byte ceiling the worker enforces +// +// On a normal run it prints one readiness line — "ShardRuntime worker listening +// on " — once the socket is bound, so a supervisor/harness has a real +// readiness signal instead of a sleep. + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include + +#include "shard_service.h" +#include "shard_runtime.grpc.pb.h" + +namespace { + +namespace sp = ::meshnet::shard::v1; + +// Self-pipe: the signal handler must stay async-signal-safe, so it only writes +// one byte; a helper thread reads it and performs the (non-signal-safe) server +// Shutdown(). Set once in main() before installing the handler. +volatile std::sig_atomic_t g_signal_pipe_write_fd = -1; + +extern "C" void HandleTermination(int /*signum*/) { + if (g_signal_pipe_write_fd >= 0) { + const char byte = 1; + ssize_t rc = ::write(g_signal_pipe_write_fd, &byte, 1); + (void)rc; // best-effort; nothing safe to do on failure inside a handler + } +} + +meshnet::worker::FlowLimits LimitsFromEnv() { + meshnet::worker::FlowLimits limits; + if (const char* raw = std::getenv("MESHNET_MAX_CHUNK_BYTES")) { + char* end = nullptr; + const unsigned long long value = std::strtoull(raw, &end, 10); + if (end != raw && value > 0) { + limits.max_chunk_bytes = static_cast(value); + } + } + return limits; +} + +int RunSelfTest() { + meshnet::worker::ShardRuntimeServiceImpl service(LimitsFromEnv()); + int selected_port = 0; + grpc::ServerBuilder builder; + builder.AddListeningPort("127.0.0.1:0", grpc::InsecureServerCredentials(), &selected_port); + builder.RegisterService(&service); + std::unique_ptr server(builder.BuildAndStart()); + if (!server || selected_port == 0) { + std::cerr << "selftest: failed to bind ephemeral port\n"; + return 1; + } + const std::string target = "127.0.0.1:" + std::to_string(selected_port); + auto channel = grpc::CreateChannel(target, grpc::InsecureChannelCredentials()); + auto stub = sp::ShardRuntime::NewStub(channel); + + int failures = 0; + auto check = [&](bool cond, const char* what) { + if (!cond) { + std::cerr << "selftest FAIL: " << what << "\n"; + ++failures; + } + }; + + // Capability + health. + { + grpc::ClientContext ctx; + sp::CapabilityRequest req; + req.set_schema_version(sp::SCHEMA_VERSION_1); + sp::CapabilityReport rep; + grpc::Status status = stub->GetCapability(&ctx, req, &rep); + check(status.ok(), "GetCapability RPC"); + check(rep.validated(), "capability validated"); + check(rep.schema_version() == sp::SCHEMA_VERSION_1, "capability schema version"); + } + { + grpc::ClientContext ctx; + sp::HealthRequest req; + req.set_schema_version(sp::SCHEMA_VERSION_1); + sp::HealthReport rep; + grpc::Status status = stub->Health(&ctx, req, &rep); + check(status.ok(), "Health RPC"); + check(rep.state() == sp::SERVING_STATE_SERVING, "health serving"); + } + + // A minimal session: open -> fragmented prefill -> decode -> release. + { + grpc::ClientContext ctx; + auto stream = stub->Session(&ctx); + + sp::SessionRequest open; + sp::SessionOpen* o = open.mutable_open(); + o->set_schema_version(sp::SCHEMA_VERSION_1); + o->set_route_session_id("selftest"); + o->set_route_epoch(1); + sp::FlowControl* fc = o->mutable_proposed_flow_control(); + fc->set_credits_granted(16); + fc->set_max_inflight_chunks(16); + fc->set_max_chunk_bytes(4u * 1024u * 1024u); + check(stream->Write(open), "write open"); + + sp::SessionResponse accepted; + check(stream->Read(&accepted), "read accepted"); + check(accepted.kind_case() == sp::SessionResponse::kAccepted, "accepted kind"); + + // Fragmented prefill: two fragments tiling a 6-byte payload. + const std::string payload = "ABCDEF"; + sp::SessionRequest chunk; + sp::ActivationChunk* ac = chunk.mutable_chunk(); + sp::Envelope* env = ac->mutable_envelope(); + env->set_schema_version(sp::SCHEMA_VERSION_1); + env->set_work_id("w1"); + env->set_route_session_id("selftest"); + env->set_route_epoch(1); + env->set_idempotency_step(1); + env->set_phase(sp::PHASE_PREFILL); + sp::TensorBundle* bundle = ac->mutable_bundle(); + bundle->set_bundle_version(1); + sp::NamedTensor* tensor = bundle->add_tensors(); + tensor->set_name("hidden_states"); + tensor->set_dtype(sp::DTYPE_BFLOAT16); + tensor->set_byte_order(sp::BYTE_ORDER_LITTLE_ENDIAN); + tensor->set_total_bytes(payload.size()); + tensor->set_compression(sp::COMPRESSION_NONE); + sp::Checksum* cksum = tensor->mutable_checksum(); + cksum->set_algorithm(sp::CHECKSUM_ALGORITHM_CRC32C); + const uint32_t crc = meshnet::worker::Crc32(payload); + std::string crc_be(4, '\0'); + crc_be[0] = static_cast((crc >> 24) & 0xFF); + crc_be[1] = static_cast((crc >> 16) & 0xFF); + crc_be[2] = static_cast((crc >> 8) & 0xFF); + crc_be[3] = static_cast(crc & 0xFF); + cksum->set_value(crc_be); + sp::TensorFragment* f0 = tensor->add_fragments(); + f0->set_fragment_index(0); + f0->set_fragment_count(2); + f0->set_byte_offset(0); + f0->set_payload(payload.substr(0, 3)); + sp::TensorFragment* f1 = tensor->add_fragments(); + f1->set_fragment_index(1); + f1->set_fragment_count(2); + f1->set_byte_offset(3); + f1->set_payload(payload.substr(3)); + check(stream->Write(chunk), "write chunk"); + + sp::SessionResponse echoed; + check(stream->Read(&echoed), "read chunk echo"); + check(echoed.kind_case() == sp::SessionResponse::kChunk, "chunk echo kind"); + + sp::SessionRequest decode; + sp::DecodeStep* ds = decode.mutable_decode(); + ds->set_idempotency_step(2); + ds->set_position(1); + ds->set_work_id("w2"); + sp::TensorBundle* dbundle = ds->mutable_bundle(); + dbundle->set_bundle_version(1); + sp::NamedTensor* dt = dbundle->add_tensors(); + dt->set_name("hidden_states"); + dt->set_dtype(sp::DTYPE_BFLOAT16); + dt->set_byte_order(sp::BYTE_ORDER_LITTLE_ENDIAN); + dt->set_total_bytes(payload.size()); + dt->set_compression(sp::COMPRESSION_NONE); + sp::Checksum* dck = dt->mutable_checksum(); + dck->set_algorithm(sp::CHECKSUM_ALGORITHM_CRC32C); + dck->set_value(crc_be); + sp::TensorFragment* df = dt->add_fragments(); + df->set_fragment_index(0); + df->set_fragment_count(1); + df->set_byte_offset(0); + df->set_payload(payload); + check(stream->Write(decode), "write decode"); + + sp::SessionResponse decode_echo; + check(stream->Read(&decode_echo), "read decode echo"); + check(decode_echo.kind_case() == sp::SessionResponse::kChunk, "decode echo kind"); + + sp::SessionRequest release; + sp::ReleaseSignal* rs = release.mutable_release(); + rs->set_route_session_id("selftest"); + rs->set_work_id("w-final"); + check(stream->Write(release), "write release"); + stream->WritesDone(); + + sp::SessionResponse terminal; + check(stream->Read(&terminal), "read terminal"); + check(terminal.kind_case() == sp::SessionResponse::kStatus && terminal.status().terminal(), + "terminal status"); + + grpc::Status status = stream->Finish(); + check(status.ok(), "stream finish"); + } + + server->Shutdown(); + server->Wait(); + + if (failures == 0) { + std::cout << "selftest: all lifecycle checks passed\n"; + return 0; + } + std::cerr << "selftest: " << failures << " check(s) failed\n"; + return 1; +} + +} // namespace + +int main(int argc, char** argv) { + GOOGLE_PROTOBUF_VERIFY_VERSION; + + for (int i = 1; i < argc; ++i) { + if (std::strcmp(argv[i], "--selftest") == 0) { + return RunSelfTest(); + } + } + + std::string listen_addr = "localhost:50051"; + if (const char* env = std::getenv("MESHNET_SHARD_LISTEN_ADDR")) { + listen_addr = env; + } + if (argc > 1 && argv[1][0] != '-') { + listen_addr = argv[1]; + } + + meshnet::worker::FlowLimits limits = LimitsFromEnv(); + meshnet::worker::ShardRuntimeServiceImpl service(limits); + + grpc::ServerBuilder builder; + int selected_port = 0; + builder.AddListeningPort(listen_addr, grpc::InsecureServerCredentials(), &selected_port); + // Bounded messages, two layers: a hard transport receive ceiling (never below + // 4 MiB so the handshake and normal chunks always fit) plus the finer + // app-level per-tensor RESOURCE_EXHAUSTED check the service enforces against + // the negotiated max_chunk_bytes. Neither path lets an unbounded frame in. + constexpr int kTransportFloor = 4 * 1024 * 1024; + const int transport_max = limits.max_chunk_bytes > static_cast(kTransportFloor) + ? static_cast(limits.max_chunk_bytes) + : kTransportFloor; + builder.SetMaxReceiveMessageSize(transport_max); + builder.RegisterService(&service); + std::unique_ptr server(builder.BuildAndStart()); + if (!server || selected_port == 0) { + std::cerr << "failed to bind " << listen_addr << "\n"; + return 1; + } + + int pipe_fds[2]; + if (::pipe(pipe_fds) != 0) { + std::cerr << "failed to create shutdown pipe\n"; + return 1; + } + g_signal_pipe_write_fd = pipe_fds[1]; + + struct sigaction sa; + std::memset(&sa, 0, sizeof(sa)); + sa.sa_handler = HandleTermination; + ::sigaction(SIGTERM, &sa, nullptr); + ::sigaction(SIGINT, &sa, nullptr); + + // Drain thread: wakes on the first termination signal and shuts the server + // down gracefully so in-flight sessions finish rather than being severed. + std::thread drain([&server, read_fd = pipe_fds[0]]() { + char byte = 0; + ssize_t rc = 0; + do { + rc = ::read(read_fd, &byte, 1); + } while (rc < 0 && errno == EINTR); + server->Shutdown(); + }); + + std::cout << "ShardRuntime worker listening on " << listen_addr << std::endl; + + server->Wait(); + drain.join(); + ::close(pipe_fds[0]); + ::close(pipe_fds[1]); + std::cout << "ShardRuntime worker shut down cleanly" << std::endl; + return 0; +} diff --git a/tests/test_native_shard_worker.py b/tests/test_native_shard_worker.py new file mode 100644 index 0000000..bad615a --- /dev/null +++ b/tests/test_native_shard_worker.py @@ -0,0 +1,498 @@ +"""DGR-033 integration tests for the standalone native C++ Shard worker. + +These tests spawn the *real* compiled ``shard_worker`` executable as a separate +OS process, connect to its real localhost socket with the committed generated +``ShardRuntimeStub`` stubs, and drive the complete lifecycle/stream contract. +There is no in-memory channel, no Python servicer, and no fake transport: the +server under test is the C++ binary DGR-033 builds. + +The worker binary is located via ``MESHNET_SHARD_WORKER_BIN`` or the default +out-of-tree build path ``build/native/shard_worker``. When it has not been +built (a default developer/CI checkout without the pinned gRPC C++ toolchain), +every test here is skipped rather than failed — the same ``requires_cmake`` +gating pattern DGR-029/DGR-030 use for native-build-dependent tests. The +session that implemented DGR-033 built the binary and ran these for real; see +``evidence/DGR-033/README.md`` for the exact commands and results. +""" + +from __future__ import annotations + +import os +import signal +import socket +import subprocess +import time +import zlib + +import grpc +import pytest + +REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) + +_PYTHONPATH = os.pathsep.join( + [os.path.join(REPO_ROOT, "packages", "node"), os.path.join(REPO_ROOT, "packages", "tracker")] +) + +from meshnet_node.native_protocol.generated import ( # noqa: E402 + shard_runtime_pb2 as pb, + shard_runtime_pb2_grpc as pb_grpc, +) + + +def _worker_binary() -> str | None: + explicit = os.environ.get("MESHNET_SHARD_WORKER_BIN") + if explicit and os.path.exists(explicit): + return explicit + default = os.path.join(REPO_ROOT, "build", "native", "shard_worker") + if os.path.exists(default): + return default + return None + + +_WORKER_BIN = _worker_binary() +pytestmark = pytest.mark.skipif( + _WORKER_BIN is None, + reason=( + "native shard_worker binary not built; build packages/node/native with the " + "pinned gRPC C++ toolchain or set MESHNET_SHARD_WORKER_BIN" + ), +) + + +def _free_port() -> int: + s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + s.bind(("127.0.0.1", 0)) + port = s.getsockname()[1] + s.close() + return port + + +def _start_worker(listen_addr: str, extra_env: dict[str, str] | None = None) -> subprocess.Popen: + env = dict(os.environ) + env["PYTHONPATH"] = _PYTHONPATH + if extra_env: + env.update(extra_env) + proc = subprocess.Popen( + [_WORKER_BIN, listen_addr], + cwd=REPO_ROOT, + env=env, + stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, + text=True, + ) + deadline = time.time() + 30.0 + while time.time() < deadline: + line = proc.stdout.readline() + if not line: + if proc.poll() is not None: + out, _ = proc.communicate() + raise RuntimeError(f"worker exited early:\n{out}") + continue + if "listening on" in line: + return proc + raise RuntimeError("worker did not start listening in time") + + +class _Worker: + """A spawned worker plus a ready channel; also captures stdout on close.""" + + def __init__(self, extra_env: dict[str, str] | None = None) -> None: + self.port = _free_port() + self.addr = f"127.0.0.1:{self.port}" + self.proc = _start_worker(self.addr, extra_env) + self.channel = grpc.insecure_channel(self.addr) + grpc.channel_ready_future(self.channel).result(timeout=15.0) + + def stub(self) -> pb_grpc.ShardRuntimeStub: + return pb_grpc.ShardRuntimeStub(self.channel) + + def session(self, requests): + call = self.channel.stream_stream( + "/meshnet.shard.v1.ShardRuntime/Session", + request_serializer=lambda m: m.SerializeToString(), + response_deserializer=pb.SessionResponse.FromString, + ) + return list(call(iter(requests))) + + def close(self, *, sig: int = signal.SIGTERM) -> str: + self.channel.close() + self.proc.send_signal(sig) + try: + out, _ = self.proc.communicate(timeout=10) + except subprocess.TimeoutExpired: + self.proc.kill() + out, _ = self.proc.communicate() + return out or "" + + +@pytest.fixture() +def worker(): + w = _Worker() + try: + yield w + finally: + if w.proc.poll() is None: + w.close() + + +def _crc32c(payload: bytes) -> bytes: + return zlib.crc32(payload).to_bytes(4, "big") + + +def _open(*, route_session_id="rs-1", route_epoch=7, credits_granted=16) -> pb.SessionRequest: + return pb.SessionRequest( + open=pb.SessionOpen( + schema_version=pb.SCHEMA_VERSION_1, + route_session_id=route_session_id, + route_epoch=route_epoch, + fingerprint=pb.Fingerprint( + model_artifact_digest="sha256:native-test-artifact", + runtime_recipe_digest="sha256:native-test-recipe", + recipe_id="native-test", + recipe_version="1", + catalogue_version="1", + ), + shard_range=pb.ShardRange(start_layer=0, end_layer=32, effective_start_layer=0), + proposed_flow_control=pb.FlowControl( + credits_granted=credits_granted, + max_inflight_chunks=16, + max_chunk_bytes=4 * 1024 * 1024, + max_prefill_chunk_tokens=512, + ), + accepted_compression=[pb.COMPRESSION_NONE], + ) + ) + + +def _chunk( + work_id, + payload: bytes, + step, + *, + route_session_id="rs-1", + route_epoch=7, + deadline_unix_nanos=0, + fragments=1, + total_bytes=None, +) -> pb.SessionRequest: + total = len(payload) if total_bytes is None else total_bytes + frags = [] + if fragments == 1: + frags = [pb.TensorFragment(fragment_index=0, fragment_count=1, byte_offset=0, payload=payload)] + else: + # Split into ``fragments`` tiling pieces. + size = max(1, len(payload) // fragments) + offset = 0 + idx = 0 + while offset < len(payload): + piece = payload[offset : offset + size] if idx < fragments - 1 else payload[offset:] + frags.append( + pb.TensorFragment( + fragment_index=idx, fragment_count=fragments, byte_offset=offset, payload=piece + ) + ) + offset += len(piece) + idx += 1 + tensor = pb.NamedTensor( + name="hidden_states", + shape=[1, 1, 4096], + dtype=pb.DTYPE_BFLOAT16, + byte_order=pb.BYTE_ORDER_LITTLE_ENDIAN, + total_bytes=total, + compression=pb.COMPRESSION_NONE, + checksum=pb.Checksum(algorithm=pb.CHECKSUM_ALGORITHM_CRC32C, value=_crc32c(payload)), + fragments=frags, + ) + bundle = pb.TensorBundle( + bundle_version=1, + tensors=[tensor], + architecture=pb.ARCHITECTURE_TYPE_DENSE, + boundary_point="pre_tail_residual", + ) + envelope = pb.Envelope( + schema_version=pb.SCHEMA_VERSION_1, + work_id=work_id, + route_session_id=route_session_id, + route_epoch=route_epoch, + idempotency_step=step, + phase=pb.PHASE_PREFILL, + position=pb.PositionSpan(first_position=0, token_count=1), + deadline_unix_nanos=deadline_unix_nanos, + ) + return pb.SessionRequest(chunk=pb.ActivationChunk(envelope=envelope, bundle=bundle)) + + +def _decode(work_id, payload: bytes, step, position) -> pb.SessionRequest: + tensor = pb.NamedTensor( + name="hidden_states", + shape=[1, 1, 4096], + dtype=pb.DTYPE_BFLOAT16, + byte_order=pb.BYTE_ORDER_LITTLE_ENDIAN, + total_bytes=len(payload), + compression=pb.COMPRESSION_NONE, + checksum=pb.Checksum(algorithm=pb.CHECKSUM_ALGORITHM_CRC32C, value=_crc32c(payload)), + fragments=[pb.TensorFragment(fragment_index=0, fragment_count=1, byte_offset=0, payload=payload)], + ) + return pb.SessionRequest( + decode=pb.DecodeStep( + idempotency_step=step, + position=position, + expected_past_len=position, + work_id=work_id, + bundle=pb.TensorBundle(bundle_version=1, tensors=[tensor], architecture=pb.ARCHITECTURE_TYPE_DENSE), + ) + ) + + +def _release() -> pb.SessionRequest: + return pb.SessionRequest( + release=pb.ReleaseSignal(route_session_id="rs-1", route_epoch=7, work_id="work-final") + ) + + +def _cancel(*, route_session_id="rs-1", work_id="", reason="test cancel") -> pb.SessionRequest: + return pb.SessionRequest( + cancel=pb.CancelSignal(route_session_id=route_session_id, route_epoch=7, work_id=work_id, reason=reason) + ) + + +# --- startup / health / capability ---------------------------------------- + + +def test_worker_startup_and_health(worker): + health = worker.stub().Health(pb.HealthRequest(schema_version=pb.SCHEMA_VERSION_1)) + assert health.state == pb.SERVING_STATE_SERVING + assert health.schema_version == pb.SCHEMA_VERSION_1 + + +def test_worker_capability(worker): + cap = worker.stub().GetCapability(pb.CapabilityRequest(schema_version=pb.SCHEMA_VERSION_1)) + assert cap.validated is True + assert cap.schema_version == pb.SCHEMA_VERSION_1 + assert cap.shard_range.end_layer == 32 + assert pb.SCHEMA_VERSION_1 in cap.supported_schema_versions + + +# --- fragmented prefill / decode / release --------------------------------- + + +def test_fragmented_prefill_echoes_reassembled_payload(worker): + payload = b"REAL_ACTIVATION_BYTES_prefill_across_three_fragments_1234567890" + responses = worker.session([_open(), _chunk("w1", payload, step=1, fragments=3), _release()]) + assert responses[0].WhichOneof("kind") == "accepted" + echoed = responses[1] + assert echoed.WhichOneof("kind") == "chunk" + got = b"".join(f.payload for f in echoed.chunk.bundle.tensors[0].fragments) + assert got == payload + assert echoed.chunk.bundle.tensors[0].checksum.value == _crc32c(payload) + assert responses[2].status.terminal is True + + +def test_decode_step_is_served(worker): + payload = b"REAL_ACTIVATION_BYTES_decode_step" + responses = worker.session([_open(), _decode("w2", payload, step=1, position=1)]) + echoed = responses[1] + assert echoed.WhichOneof("kind") == "chunk" + assert echoed.chunk.envelope.phase == pb.PHASE_DECODE + assert echoed.chunk.bundle.tensors[0].fragments[0].payload == payload + + +def test_release_is_terminal(worker): + responses = worker.session([_open(), _release()]) + assert responses[0].WhichOneof("kind") == "accepted" + assert responses[1].status.terminal is True + + +# --- deadlines / flow control / bounded messages --------------------------- + + +def test_expired_deadline_is_rejected(worker): + responses = worker.session([_open(), _chunk("w-late", b"payload", step=1, deadline_unix_nanos=1)]) + assert responses[1].status.error.code == pb.ERROR_CODE_DEADLINE_EXCEEDED + + +def test_flow_control_violation_and_topup(worker): + responses = worker.session( + [ + _open(credits_granted=1), + _chunk("w-a", b"payload-a", step=1), + _chunk("w-b", b"payload-b", step=2), + pb.SessionRequest(flow_control=pb.FlowControl(credits_granted=5)), + _chunk("w-c", b"payload-c", step=3), + ] + ) + assert responses[1].WhichOneof("kind") == "chunk" + assert responses[2].status.error.code == pb.ERROR_CODE_FLOW_CONTROL_VIOLATION + assert responses[2].status.error.retryable is True + assert responses[3].WhichOneof("kind") == "flow_control" + assert responses[3].flow_control.credits_granted >= 5 + assert responses[4].WhichOneof("kind") == "chunk" + + +def test_bounded_message_is_rejected(): + """A tensor whose declared payload exceeds the negotiated ceiling is refused.""" + w = _Worker(extra_env={"MESHNET_MAX_CHUNK_BYTES": "64"}) + try: + big = b"x" * 128 + responses = w.session([_open(), _chunk("w-big", big, step=1, total_bytes=128)]) + status = responses[1].status + assert status.error.code == pb.ERROR_CODE_RESOURCE_EXHAUSTED + assert "max_chunk_bytes" in status.error.detail + finally: + if w.proc.poll() is None: + w.close() + + +def test_malformed_fragment_tiling_is_rejected(worker): + # A fragment at a non-zero offset with no predecessor cannot tile. + tensor = pb.NamedTensor( + name="hidden_states", + shape=[1, 1, 4096], + dtype=pb.DTYPE_BFLOAT16, + byte_order=pb.BYTE_ORDER_LITTLE_ENDIAN, + total_bytes=7, + compression=pb.COMPRESSION_NONE, + checksum=pb.Checksum(algorithm=pb.CHECKSUM_ALGORITHM_CRC32C, value=_crc32c(b"payload")), + fragments=[pb.TensorFragment(fragment_index=0, fragment_count=1, byte_offset=5, payload=b"payload")], + ) + bad = pb.SessionRequest( + chunk=pb.ActivationChunk( + envelope=pb.Envelope( + schema_version=pb.SCHEMA_VERSION_1, + work_id="w-gap", + route_session_id="rs-1", + route_epoch=7, + idempotency_step=1, + ), + bundle=pb.TensorBundle(bundle_version=1, tensors=[tensor]), + ) + ) + responses = worker.session([_open(), bad]) + assert responses[1].status.error.code == pb.ERROR_CODE_PAYLOAD_CORRUPT + assert "tile" in responses[1].status.error.detail + + +def test_stale_route_epoch_is_rejected(worker): + responses = worker.session([_open(route_epoch=7), _chunk("w-stale", b"payload", step=1, route_epoch=5)]) + assert responses[1].status.error.code == pb.ERROR_CODE_EPOCH_STALE + + +def test_duplicate_idempotency_step_is_acked(worker): + chunk = _chunk("w-dup", b"payload", step=1) + responses = worker.session([_open(), chunk, chunk]) + assert responses[1].WhichOneof("kind") == "chunk" + assert responses[2].WhichOneof("kind") == "ack" + assert responses[2].ack.duplicate is True + + +# --- cancellation ---------------------------------------------------------- + + +def test_in_band_cancel_of_single_work_item_does_not_end_stream(worker): + responses = worker.session( + [ + _open(), + _cancel(work_id="work-x"), + _chunk("work-x", b"payload", step=1), + _chunk("work-y", b"payload", step=2), + _release(), + ] + ) + assert responses[1].status.error.code == pb.ERROR_CODE_CANCELLED + assert responses[1].status.terminal is False + assert responses[2].status.error.code == pb.ERROR_CODE_CANCELLED + assert responses[3].WhichOneof("kind") == "chunk" + assert responses[4].status.terminal is True + + +def test_in_band_cancel_of_whole_session_is_terminal(worker): + responses = worker.session([_open(), _cancel(work_id="")]) + assert responses[1].status.error.code == pb.ERROR_CODE_CANCELLED + assert responses[1].status.terminal is True + + +def test_out_of_band_cancel_rpc_races_ahead_of_open(worker): + stub = worker.stub() + resp = stub.Cancel( + pb.CancelRequest( + schema_version=pb.SCHEMA_VERSION_1, + route_session_id="rs-precancel", + route_epoch=1, + work_id="work-precancelled", + reason="operator abort", + ) + ) + assert resp.cancelled_work_items == 1 + responses = worker.session( + [ + _open(route_session_id="rs-precancel"), + _chunk("work-precancelled", b"payload", step=1, route_session_id="rs-precancel"), + ] + ) + assert responses[1].status.error.code == pb.ERROR_CODE_CANCELLED + + +def test_release_rpc_is_idempotent(worker): + stub = worker.stub() + # Open a session so state exists, then release it out of band twice. + worker.session([_open(route_session_id="rs-rel"), _release()]) + # (release signal in-stream does not erase state; the unary Release RPC does) + first = stub.Release(pb.ReleaseRequest(schema_version=pb.SCHEMA_VERSION_1, route_session_id="rs-rel", route_epoch=7)) + second = stub.Release(pb.ReleaseRequest(schema_version=pb.SCHEMA_VERSION_1, route_session_id="rs-rel", route_epoch=7)) + assert first.released is True + assert second.released is False # idempotent: nothing left to drop + + +def test_independent_session_cancellation(worker): + # Cancel the whole of session A; session B must remain fully serviceable. + a = worker.session([_open(route_session_id="sess-A"), _cancel(route_session_id="sess-A", work_id="")]) + assert a[1].status.terminal is True + b = worker.session( + [ + _open(route_session_id="sess-B"), + _chunk("work-b", b"payload-b", step=1, route_session_id="sess-B"), + _release(), + ] + ) + assert b[1].WhichOneof("kind") == "chunk", "cancelling session A must not affect session B" + + +# --- graceful shutdown ----------------------------------------------------- + + +def test_graceful_shutdown_on_sigterm(): + w = _Worker() + # Confirm it is serving, then send SIGTERM and require a clean drain/exit. + assert w.stub().Health(pb.HealthRequest(schema_version=pb.SCHEMA_VERSION_1)).state == pb.SERVING_STATE_SERVING + out = w.close(sig=signal.SIGTERM) + assert w.proc.returncode == 0, f"worker did not exit cleanly on SIGTERM:\n{out}" + assert "shut down cleanly" in out + + +# --- direct vs opaque relay byte identity ---------------------------------- + + +def test_direct_and_opaque_relay_yield_identical_responses(worker): + """A direct hop and an opaque relay of the exact captured request bytes must + produce byte-identical server responses (relays carry frames verbatim).""" + payload = b"RELAY_ACTIVATION_BYTES" + requests = [_open(), _chunk("w1", payload, step=1), _release()] + + direct_call = worker.channel.stream_stream( + "/meshnet.shard.v1.ShardRuntime/Session", + request_serializer=lambda m: m.SerializeToString(), + response_deserializer=lambda b: b, + ) + direct_resp = list(direct_call(iter(requests))) + captured = [m.SerializeToString() for m in requests] + + relay_call = worker.channel.stream_stream( + "/meshnet.shard.v1.ShardRuntime/Session", + request_serializer=lambda b: b, # raw captured bytes, no reinterpretation + response_deserializer=lambda b: b, + ) + relay_resp = list(relay_call(iter(captured))) + + assert len(direct_resp) == len(relay_resp) == 3 + for i, (d, r) in enumerate(zip(direct_resp, relay_resp)): + assert d == r, f"response #{i} differs between direct and opaque relay"