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