# 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

```text
$ 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.