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

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 — delayed-review repair, 2026-07-14

DGR-003 defines and tests an exact, model-agnostic compatibility identity and connects it to DGR-002's gRPC Fingerprint plus tracker parsing, admission, route partitioning, and certification. It is not complete: the existing production doctor/backend path still emits the legacy capability report without constructing a ShardIdentity from authoritative loaded artifact/runtime state. No exact recipe is therefore claimed live or routable from that path; supplied exact identities remain dark until tracker-owned certification.

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_session_open() fails closed on schema, fingerprint, advertised/effective range, non-empty route session, positive route epoch, and (when supplied) exact tracker route-session/epoch assignment.
• 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 the sole live 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. Restart fails closed; durable/cluster-wide certification events require the later real-forward control path and are not claimed here.
• 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/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 during delayed DGR-003 review: 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: 126 passed.
• DGR-017 focused dependency repair suite: 99 passed.
• Tracker routing suite: 93 passed.
• First delayed-review integrated run: 898 passed, 13 skipped, 1 failed on the pre-existing tracker-cancellation race.
• Final delayed-review integrated rerun: 899 passed, 13 skipped in 253.64s; Hermes controller acceptance rerun: 899 passed, 13 skipped in 252.66s.
• 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. In this delayed repair it again produced a 404 after the stream finished (first integrated run: 898 passed, 13 skipped, 1 failed); three immediate isolated repeats passed before a fourth reproduced the same race. No cancellation-test code was changed. The final complete integrated rerun passed 899/899 tests.

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 has no certification ledger or admission policy; it holds only identity construction and handshake validation. The Tracker is the sole promotion authority.
• Completion blocker: doctor._validate_recipe() calls build_capability_report() without identity=, because the legacy Transformers backend does not expose an immutable artifact-content pin and full runtime recipe axes authoritative enough to build one. Adding a guessed identity would weaken this contract. Production emission must be added with the authoritative native worker/backend loading seam; until then the issue and PRD deliberately remain incomplete.
• 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.

Native emission closure — 2026-07-14

Status: done. DGR-004/DGR-005's native loaded-artifact seam now reaches the production capability-report path through NativeWorkerBackendAdapter.

Files changed

• packages/node/meshnet_node/native_backend.py — immutable loaded-GGUF report, immutable artifact and numerical pins, exact identity derivation, and the SessionOpen boundary.
• packages/node/meshnet_node/doctor.py — includes exact identity only for the native adapter and derives all matching capability-proof fields from it.
• tests/test_native_identity_emission.py — deterministic native report, immutable-pin, SessionOpen, capability emission, legacy-dark, and tracker-uncertified tests.
• This issue, prd.json, and this evidence directory.

Correctness and trust boundary

The native report carries the end-exclusive owned range, mapped/resident/ registered bytes, GGUF architecture metadata digest, and layer count. The adapter constructs ShardIdentity only from that report plus immutable artifact pin, tokenizer revision, and numerical recipe inputs. It does not accept a caller-supplied shard range.

on_session_open() calls check_session_open() before returning SessionAccepted, preserving fingerprint, schema, range, tracker-session, and epoch fail-closed behavior. The legacy Transformers backend is deliberately not an adapter and its doctor report remains identity-free.

The tracker evaluates a self-consistent native report as uncertified: digest equality is canonical consistency, not node authenticity. Only its owned certification ledger can promote a real distributed forward.

Verification

• Focused/adversarial DGR-003, node/tracker capability, doctor, and native dependency suites: 171 passed, 1 skipped.
• Native protocol CMake configure/build plus CTest: 1/1 passed.
• compileall, Ruff, and git diff --check: pass.
• Full deterministic suite: 902 passed, 13 skipped (255.01s).

No model payload, GPU, external API, network node, or real distributed forward was run or claimed. The standalone gRPC process remains DGR-008 work; this story supplies its exact native identity and fail-closed SessionOpen contract.