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.

**Assignment ownership:** NCA validates whatever the node loads; it does not assign models. Pinned vs tracker-managed assignment rules are in [ADR-0026](../../docs/adr/0026-node-assignment-ownership-and-managed-placement.md). Demand-driven managed placement (Qwen scratch PRD) may only consume spare capacity; admission applies equally to pinned and managed loads.

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.