# 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.