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.

4.5 KiB Raw Blame History