DGR-022 evidence — Shard lifecycle and structured status RPC contract

Completed: 2026-07-17 Branch: ralph/distributed-gguf-runtime Authority: .scratch/distributed-gguf-runtime/prd.json

Outcome

Implemented the versioned, backend-neutral lifecycle/status contract consumed by a future generated gRPC binding. The contract keeps Meshnet routing, identity, authentication policy, billing, and llama.cpp ownership outside the worker contract.

Implemented

packages/node/meshnet_node/shard_lifecycle.py
- capability, health, session, cancellation, release, and metrics RPC names
- schema version negotiation and fail-closed unsupported-version handling
- structured status/error taxonomy with retryability and details
- lifecycle state machine for prefill/decode/cancel/release transitions
- monotonic idempotency-step enforcement and duplicate rejection
- bounded frame/byte flow control with cancellation-aware waits
- explicit cache expectation/result types
- deadline policy and TLS/auth transport hooks
- deterministic contract serialization round-trip
tests/test_shard_lifecycle.py
- contract round-trip and RPC coverage
- unsupported-version rejection
- malformed transition and idempotency rejection
- cancellation/release behavior
- bounded flow-control behavior
- TLS hook and incomplete-contract fail-closed behavior

Verification

$ PYTHONPATH=packages/node pytest -q tests/test_shard_lifecycle.py tests/test_activation_envelope.py
17 passed in 0.10s

The existing DGR-021 activation-envelope tests remain green alongside DGR-022.

Scope limitation

This story defines the lifecycle/status contract only. Generated Python/C++ protobuf bindings and the concrete shard_runtime.proto generation pipeline are DGR-023 and remain separate.

Dependency handoff

DGR-023 may consume the RPC names, status taxonomy, version identity, deadlines, flow-control limits, and TLS/auth hooks when the canonical .proto schema and toolchain are provisioned.

2.0 KiB Raw Blame History