120 lines
5.7 KiB
Markdown
120 lines
5.7 KiB
Markdown
# 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.
|