47 lines
2.0 KiB
Markdown
47 lines
2.0 KiB
Markdown
# 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.
|