feat: DGR-003 - Define exact Artifact and runtime recipe identity

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

@@ -0,0 +1,119 @@
+# DGR-003 — exact Artifact and runtime recipe identity
+
+Evidence class: deterministic offline/unit. No model payload, GPU, external API,
+network node, or API credit is required or claimed.
+
+## Result
+
+DGR-003 defines an exact, model-agnostic compatibility identity and connects it
+to both DGR-002's gRPC `Fingerprint` and tracker capability admission.
+
+A matching digest proves canonical consistency, **not node authenticity or real
+execution**. Tracker-owned certification of a fingerprint by a non-synthetic,
+complete, multi-node distributed forward is the execution trust boundary.
+
+## Implementation
+
+- `ArtifactIdentity` binds artifact ID/revision, exact content digest,
+  architecture/config digest, layer count, and optional derivative binding.
+- `DerivativeBinding` binds a split artifact to the exact source artifact digest
+  and its end-exclusive layer range. A Shard cannot advertise outside that range.
+- `RuntimeRecipe` keeps these canonical axes separate rather than hiding them in
+  a backend label:
+  - weight quantization;
+  - activation and compute dtypes;
+  - KV dtype and layout;
+  - tokenizer revision;
+  - architecture adapter;
+  - backend and runtime version;
+  - boundary and protocol schema versions;
+  - recipe ID/version and catalogue version.
+- `CompatibilityFingerprint` populates the existing DGR-002 Protobuf
+  `Fingerprint`; `check_handshake()` returns DGR-002's structured fingerprint
+  mismatch error.
+- Node and tracker implementations independently canonicalize the declaration.
+  This is intentional: the tracker must not trust a digest copied from a node,
+  and future native/C++ workers also need an independent implementation. Their
+  behavior is pinned by `tests/data/recipe_fingerprint_vectors.json`.
+- Tracker admission cross-checks the exact identity against the capability
+  proof's model, range, recipe labels, backend, and weight quantization. Any
+  disagreement fails closed.
+- `TrackerServer` owns one certification ledger and passes it through direct and
+  replicated registration paths. A known exact recipe is `uncertified` and dark
+  for user traffic until the same exact fingerprint is certified.
+- Certification evidence is bound to the promoted fingerprint, requires at
+  least two distinct nodes, complete layer coverage, generated tokens, and
+  `synthetic=false`. Unknown or mismatched fingerprints cannot be promoted.
+
+## Files changed
+
+- `packages/node/meshnet_node/runtime_recipe.py`
+- `packages/node/meshnet_node/capability.py`
+- `packages/tracker/meshnet_tracker/recipe.py`
+- `packages/tracker/meshnet_tracker/capability.py`
+- `packages/tracker/meshnet_tracker/server.py`
+- `tests/data/recipe_fingerprint_vectors.json`
+- `tests/test_runtime_recipe_identity.py`
+- this evidence directory, issue state, and DGR-003 PRD state
+
+A late review of dependency DGR-017 also found and fixed two genuine contract
+continuity defects before DGR-003 was accepted: v1 now has an independently
+trusted digest and recursively immutable parsed state. Those changes and tests
+are recorded in DGR-017 evidence rather than claimed as DGR-003 functionality.
+
+## Verification
+
+Exact commands and outcomes are in `commands.txt`.
+
+Observed final results:
+
+- DGR-003 identity + node/tracker capability suites: **99 passed**.
+- DGR-017 focused dependency repair suite: **99 passed**.
+- Full deterministic suite: **872 passed, 13 skipped**.
+- `python -m compileall -q packages tests`: pass.
+- `git diff --check`: pass.
+- Ruff on the changed identity, capability, contract, and test modules: pass.
+- `server.py` has 8 pre-existing Ruff findings at both pushed baseline and the
+  current tree; DGR-003 added no finding.
+
+The first integrated full-suite run produced **871 passed, 13 skipped, 1 failed**
+on the known unrelated
+`test_tracker_dashboard_can_cancel_inflight_proxy` timing race. Its fixture
+completed after three seconds just before cancellation, so the cancel endpoint
+returned 404. The same test then passed **5/5 in isolation**, and the complete
+integrated rerun passed **872/872** tests. No cancellation-test code was changed.
+
+## Limitations
+
+- Certification state is process-local in this story. The same running tracker
+  reuses it across registrations, but durable/cluster-wide certification-event
+  persistence belongs with the later real distributed-forward control path.
+  Restart or failover therefore returns exact recipes to the safe dark state;
+  it never makes an unsupported recipe routable.
+- The node module still contains a local registry helper from the interrupted
+  partial implementation. It has no call sites and is not used by admission;
+  tracker remains the live certification authority. Removing that unpushed
+  helper is safe cleanup, not an acceptance dependency.
+- This story proves identity and admission behavior with deterministic fixtures.
+  It does not claim a real GLM forward or hardware certification.
+
+## Compatibility
+
+- Capability report identity is additive. Legacy reports without the new block
+  retain ADR-0023's explicit compatibility-policy behavior.
+- Reports that opt into exact identity are held to it and fail closed on malformed,
+  inconsistent, unknown, dark, or mismatched declarations.
+- No new wire identity was invented; DGR-002's `Fingerprint` remains the gRPC
+  representation.
+
+## Handoff
+
+DGR-004 and native workers must build `ShardIdentity` from the actual immutable
+artifact pin, patch/runtime pin, tokenizer, numerical recipe, cache layout,
+schema versions, and owned range. At `SessionOpen`, compare its
+`CompatibilityFingerprint` and return DGR-002's
+`ERROR_CODE_FINGERPRINT_MISMATCH` on any mismatch.
+
+A digest match is not certification. Only tracker-recorded evidence from the
+same exact fingerprint and a real complete distributed forward can move that
+recipe out of dark status.