neuron-tai/docs/adr/0023-model-agnostic-node-capability-admission.md

ADR-0023: Model-agnostic Node capability admission

Status: Accepted (P0 planned)

Context

A Node currently inventories hardware, benchmarks a generic Torch operation, loads its model, registers with the Tracker, and can be routed before its exact model/backend path has completed a bounded real forward. Optional JIT or model-kernel failures can therefore surface only after a live /forward request reaches the Node.

This is incompatible with a consumer-grade node experience. A Node must never advertise a Shard it cannot actually execute. The solution must not be coupled to a development model; model-specific hardcoding would recreate the support burden for every new Model Artifact.

Decision

• Introduce a generic versioned capability report keyed by Model Artifact identity, Shard range, named recipe, backend/device identity, and local validation result.
• A recipe is data and can be one of several possible execution paths for the same Model Preset. Every recipe validates itself using a bounded real forward.
• meshnet-node doctor validates the selected model/shard by default. An explicit all-recipes mode supports CI and diagnosis.
• Startup fails closed for an explicitly selected Model Preset when no matching recipe validates. The Node must not become routable or accept paid work.
• Nodes register only locally validated capabilities. The Tracker routes only matching validated capabilities and uses measured performance as part of normal route selection.
• P0 carries the version of a local recipe manifest. New executable recipes arrive only through signed Node releases in a future feature. P0 does not download executable recipes, dynamically install dependencies, install OS packages/drivers, or implement an updater.
• A future Tracker-provided Model Artifact Manifest may be signed data only; it cannot instruct a Node to execute arbitrary code.

Consequences

• First startup has a bounded validation cost before registration, but failures occur before traffic rather than under a paid request.
• The registration and routing protocols gain compatibility/capability fields and require a transition policy for older Nodes.
• Hardware support claims become evidence-based and can be tested independently of specific development models.
• The signed Node update channel is deliberately deferred until this capability contract is stable.