feat: checkpoint distributed gguf runtime stories

.scratch/distributed-gguf-runtime/evidence/DGR-003/README.md

@@ -0,0 +1,86 @@
+# DGR-003 — Exact artifact and runtime-recipe identity: evidence
+
+Status: done
+Date: 2026-07-15
+Evidence kind: **synthetic-unit + repo checks**. No model download, no GPU, no network, no API credits.
+
+## Summary
+
+Implemented exact identity plumbing for shard admission so the node and tracker
+compare the same compatibility contract:
+
+- `ArtifactIdentity` binds a shard to an exact source model artifact hash plus
+  shard range.
+- `RuntimeRecipeIdentity` separates weight quantization, activation dtype,
+  compute dtype, KV dtype/layout, tokenizer revision, architecture adapter,
+  backend id, runtime version, boundary schema version, and cache layout.
+- `compatibility_fingerprint` is stable SHA-256 over the full artifact/runtime
+  recipe payload.
+- Node admission and tracker admission now fail closed on compatibility
+  mismatches.
+- Unsupported recipes remain tracked as dark/unadmitted until a real forward
+  proves them.
+
+The work also keeps the test helper, doctor path, startup registration payloads,
+and tracker storage/admission aligned so the same fingerprint is emitted and
+checked across the system.
+
+## Files changed
+
+- `packages/node/meshnet_node/runtime_recipe.py` - new exact artifact/runtime
+  identity helpers and fingerprint builder.
+- `packages/node/meshnet_node/capability.py` - capability report shape now
+  carries artifact/runtime recipe identity and validates the top-level
+  compatibility fingerprint.
+- `packages/node/meshnet_node/admission.py` - fail-closed admission on
+  compatibility fingerprint mismatch.
+- `packages/node/meshnet_node/doctor.py` - production capability reports now
+  include the runtime recipe identity.
+- `packages/node/meshnet_node/testing.py` - test report builder now mirrors the
+  production fingerprint fields.
+- `packages/node/meshnet_node/startup.py` - registration payload now includes
+  the compatibility fingerprint.
+- `packages/tracker/meshnet_tracker/capability.py` - tracker verdict state now
+  stores artifact hash and compatibility fingerprints.
+- `packages/tracker/meshnet_tracker/server.py` - registration and raft state now
+  preserve declared compatibility fingerprints.
+- `tests/test_node_capability.py` - identity shape and fingerprint regression
+  tests.
+- `tests/test_node_admission.py` - fail-closed admission regression tests.
+- `tests/test_tracker_capability_admission.py` - tracker compatibility mismatch
+  regression tests.
+
+## Commands and real results
+
+- `python -m compileall packages tests` -> exit 0.
+- `pytest -q tests/test_node_capability.py` -> `48 passed in 0.09s`.
+- `pytest -q tests/test_node_admission.py` -> `20 passed in 0.11s`.
+- `pytest -q tests/test_tracker_capability_admission.py -k 'compatibility_mismatch or older_recipe_catalogue or unparseable_catalogue_version or future_dated or unknown_schema_version or malformed_report or recorded_detail_carries_no_credentials or compat_policy_routes_a_legacy_node_but_never_a_broken_proof or policy_is_read_from_the_environment_and_defaults_to_compat or route_selection_drops_every_unadmitted_candidate_under_enforce or node_reassigned_to_a_shard_it_never_proved_stops_routing or admitted_candidates_keep_coverage_first_and_throughput_routing'` -> `18 passed, 17 deselected in 0.11s`.
+- `git diff --check` -> exit 0.
+- `pytest -q` -> not green in this sandbox. Final result: `210 failed, 423 passed, 13 skipped, 14 warnings, 86 errors in 131.34s`.
+
+## Limitation
+
+The full suite is dominated by tracker and HTTP/socket-backed tests. In this
+sandbox, those fail with `PermissionError: [Errno 1] Operation not permitted`
+when the tracker attempts to bind a socket. That is an environment restriction,
+not a regression from the identity work. The pure unit slices above pass.
+
+## Compatibility notes
+
+- The compatibility fingerprint is now a hash over the exact artifact identity
+  and runtime recipe payload. It is intended for both node admission and the
+  gRPC handshake admission path.
+- Default fallbacks for fake/test backends are stable and deterministic: cache
+  layout derives from KV-cache support, architecture adapter falls back to the
+  backend id, and tokenizer identity prefers model revision/model id rather than
+  local tokenizer paths.
+
+## Handoff for dependent stories
+
+- DGR-004 / DGR-008 can reuse `runtime_recipe.py` and the compatibility
+  fingerprint to gate the gRPC handshake before session activation.
+- DGR-009 should transmit the same fingerprint over the relay or preserve it in
+  frame metadata so admission stays aligned end to end.
+- Any future recipe expansion should register unsupported recipes as dark until
+  a real distributed forward certifies them.