141 lines
7.1 KiB
Markdown
141 lines
7.1 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 — 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.
|