87 lines
4.5 KiB
Markdown
87 lines
4.5 KiB
Markdown
# 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.
|