neuron-tai/.scratch/node-capability-admission/PRD.md

PRD: Model-agnostic Node capability admission

Overview

Make a Node demonstrate that it can execute the selected Model Artifact and assigned Shard before the Tracker exposes it in an Inference Route. The current flow registers a Node after a hardware inventory and synthetic Torch benchmark, but before any real model forward; optional backend/JIT failures can therefore occur on paid traffic.

The solution is generic by design. It must not hardcode Qwen3.6, FLA, Triton, CUDA, ROCm, or any other model/backend name into the capability contract. Qwen3.6 may be used only by opt-in development integration tests.

Goals

• Provide meshnet-node doctor to emit a machine-readable and human-readable capability report for the selected model/shard.
• Require a successful real forward on the selected execution path before a Node becomes routable.
• Track named recipes as data, allowing more than one validated implementation for one Model Preset.
• Let the Tracker schedule only a Node/model/shard/recipe combination that the Node validated locally.
• Preserve current generic Hugging Face model support and backward-compatible protocol behavior where possible.

Quality gates

Every user story:

• Runs its targeted pytest tests.
• Runs full pytest before completion, or records the exact unrelated failure.
• Keeps default tests deterministic, model-download-free, and GPU-free.

Release/hardware CI:

• Runs an integration-marked real-model doctor smoke test per certified hardware lane.
• Passes the model ID, source, and expected backend through environment/configuration; no test has a Qwen-specific default.

User stories

NCA-001: Generic capability and recipe report

As a Node operator, I need a model-agnostic capability report so that readiness is based on the executable model/shard/backend combination, not a generic GPU claim.

NCA-002: Doctor selected model/shard

As a Node operator, I need meshnet-node doctor to validate the selected model/shard with a real forward before I join the network.

NCA-003: Fail-closed startup admission

As a Node operator, I need startup to remain non-routable when the selected recipe fails so that a Node never accepts paid work it cannot execute.

NCA-004: Tracker validated-recipe routing gate

As a client, I need the Tracker to select only validated Node capabilities so that an Inference Route does not include a Node that merely claims compatibility.

NCA-005: Model-agnostic operations and certified-lane verification

As an operator and release engineer, I need clear doctor output and opt-in hardware-lane test instructions so that failures are actionable without exposing Python/JIT internals to ordinary users.

Functional requirements

1. The local capability report identifies the Model Artifact by generic model ID/revision/config fingerprint, shard range, selected recipe ID/version, device/backend identity, success/failure status, diagnostics, and measured validation duration.
2. A recipe is data, not a model-specific code branch. A model may offer multiple recipes; a recipe is valid only after its own real forward succeeds.
3. doctor defaults to the selected model/shard and does not search/download/test unrelated models. --all-recipes is explicit.
4. Startup must execute or consume a fresh matching validation before ready registration. A failed selected recipe exits non-zero before routable registration.
5. The Tracker records validated capabilities and excludes invalid, absent, stale, model-mismatched, shard-mismatched, or catalogue-version-incompatible capabilities from route selection.
6. The tracker protocol remains tolerant of old Nodes only during a documented compatibility window; old registrations are not eligible for routes requiring admission proof.
7. The Node reports a versioned local recipe-manifest version. P0 has no remote executable recipe download, dependency installer, self-updater, driver installer, or GUI.

Non-goals

• A signed Node auto-updater or dynamic executable recipe delivery.
• Automatic installation of OS packages, compilers, drivers, or Python dependencies.
• A native NiceHash-style desktop manager.
• Supporting or certifying a particular model, GPU vendor, OS, or optional-kernel library.
• Replacing the existing Model Artifact/assignment protocol.

Architecture

Add a small generic capability domain object in the node package. doctor loads the requested generic model path through the same backend startup uses, executes a bounded real forward at the assigned Shard, and emits the report. Startup gates routable registration on the successful report. Registration carries validated capabilities; the tracker persists/exposes them and filters route candidates at the model/shard/recipe seam.

The future signed-update contract is represented only by a local manifest version and generic schema in P0. A future Tracker Model Artifact Manifest may be signed data, but Node executable behavior remains supplied by signed Node releases.

Success measures

• A backend failure that formerly appeared on the first /forward is caught by doctor and prevents ready registration.
• A Tracker route never includes an unvalidated capability in deterministic tests.
• The same implementation works for arbitrary test model identifiers supplied by fixtures/configuration, with no Qwen-specific branch.

Open follow-up

Specify and build the signed Node release/update channel as a separate product feature after the capability contract has proved stable.