NVIDIA / NVIDIA/NemoClaw

[Architecture][Installer] Remove authoritative platform identity from pre-Node Bash

Open
#11,133 0 comments 0 reactions 0 assignees View on GitHub
area: architecture area: install needs: design platform: dgx-spark platform: dgx-station platform: jetson platform: n1x platform: wsl refactor
Dominant language
TypeScript
Stars
22.5k
Forks
3.1k
Avg merge
1d 1h
Merged PRs (30d)
715

Description

## Problem

NemoClaw does not have one architectural owner for platform identity and qualification.

The public installer must identify Express candidates before Node.js is available, while readiness, inference, policy, and topology consumers run after Node.js is available. This has produced parallel implementations:

- `scripts/install.sh` detects WSL and independently validates Spark/N1x FastOS and PCI evidence.
- `scripts/prepare-dgx-station-host.sh` contains a general NVIDIA firmware classifier for Spark, Station, other Station generations, and Jetson, even though the helper is nominally Station-specific.
- TypeScript repeats platform collection and classification across platform, preflight, inference, and readiness modules.
- Remote Station and cluster probes carry Python adapters for overlapping firmware and PCI evidence.
- Jetson host preparation uses a separate L4T signal from the post-Node platform classifier.

PR #10914 deliberately preserves this bootstrap structure while fixing DGX Station qualification. The result is safe and tested, but Bash remains an authoritative identity implementation and cross-language parity tests are required to prevent drift.

## Objective

Create a general platform-identity subsystem in which Bash is not the authoritative owner of platform identity or qualification.

Bash may remain responsible for bootstrapping, a deliberately non-authorizing candidate hint, and narrowly scoped privileged command execution. Supported-platform decisions and reason codes should come from one canonical qualification model consumed by installer, readiness, inference, policy, and topology paths.

## Design requirements

1. Define structured `PlatformIdentityEvidence` and `PlatformQualificationResult` contracts with explicit hardware, software, runtime, consistency, and reason-code fields.
2. Move general NVIDIA platform classification above Station-specific and inference-specific modules.
3. Separate fact collection from classification:
- pre-Node installer/bootstrap adapter;
- local Node/TypeScript collector;
- remote probe adapter where required.
4. Decide and document the bootstrap transition:
- stage a verified temporary runtime before authoritative classification; or
- retain only a non-authorizing pre-Node candidate hint and perform authoritative qualification before platform-specific mutation.
5. Ensure the authoritative result is revalidated at the mutation boundary. Do not trust mutable environment variables, a caller-authored JSON document, or an unsigned/stale qualification receipt.
6. Preserve standalone/reboot/resume behavior and remote-host qualification.
7. Use one canonical cross-language conformance corpus for unavoidable adapters.

## Acceptance criteria

- `prepare-dgx-station-host.sh` no longer owns general Spark, Jetson, N1x, or cross-platform firmware classification.
- `install.sh` and platform preparation scripts do not contain authoritative copies of product-name, release-version, or PCI identity policy. Any retained Bash detection is explicitly non-authorizing.
- Readiness, NIM/local inference, installer selection, direct-GPU policy, managed-cluster discovery, and dual-Station topology consume the same qualification contract.
- WSL detection has one TypeScript owner instead of separate implementations in platform and preflight modules.
- N1x FastOS and PCI qualification has one semantic owner across installer and TypeScript paths.
- Station behavior from #10914 remains unchanged:
- descriptive display values remain diagnostic;
- bounded conflict-free firmware plus exact GB300 PCI evidence owns hardware identity;
- unknown or unsafe software remains blocked;
- validation-only intent stops before onboarding.
- Explicit Express-only flags still fail before unrelated host mutation.
- Missing, malformed, oversized, conflicting, replaced, or incomplete evidence continues to fail closed.
- Existing supported-platform and agent behavior does not expand as part of this refactor.
- Architecture documentation identifies the owner, adapters, trust boundary, sequencing, and deletion of legacy classifiers.

## Suggested delivery sequence

1. Land the shared evidence/result contracts and reason codes without changing behavior.
2. Consolidate TypeScript WSL, NVIDIA firmware, N1x, and Station classification behind that contract.
3. Introduce the selected pre-Node bootstrap adapter and mutation-boundary revalidation.
4. Migrate installer and preparation callers.
5. Migrate remote probes and topology consumers.
6. Delete legacy Bash/TypeScript classifiers and reduce parity tests to the remaining adapter boundaries.

## Out of scope

- Changing which hardware or software profiles NemoClaw supports.
- Relaxing current fail-closed qualification or release allowlists.
- Reworking PR #10914 after it lands.
- Replacing the entire public installer in this issue; track broader distribution work in #8377.

## Related work

- #10914
- #10928
- #8377
- #8379

Contributor guide

Open the contributing guide

Research direction

Begin with scripts/install.sh and scripts/prepare-dgx-station-host.sh, then trace the TypeScript platform, preflight, inference, readiness, policy, and topology consumers. Define the shared evidence and qualification contracts, migrate the named callers and remote adapters, and verify that legacy authoritative classifiers are removed while fail-closed behavior, resume flows, and platform support remain unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
bash, typescript
Domain
devops, tooling
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.