NVIDIA / NVIDIA/NemoClaw

Reconcile v0 config exports with the v1 YAML contract

Open
#11,977 1 comment 0 reactions 1 assignee Claimed by @kaofelix View on GitHub
Dominant language
TypeScript
Stars
22.5k
Forks
3.1k
Avg merge
1d 1h
Merged PRs (30d)
715

Description

## Problem Statement

The v0 `nemoclaw config export` output and the v1 configuration contract have drifted apart. A v0 export cannot currently be consumed directly by the v1 `validate`, `plan`, and future `apply` operations tracked by #10904.

PR #11813 added a narrow bridge for hosted NVIDIA E2E parity. That bridge is useful for proving the workflow, but maintaining a separate translation layer in v1 would leave two configuration contracts and duplicate mapping logic.

The maintainers have confirmed that the existing v0 export shape has no known compatibility requirement that prevents us from changing it. The intended consumer is the v1 OpenTofu provider. We should therefore adapt the v0 exporter to produce the v1 shape directly.

## Agreed Direction

Change the v0 exporter so that a supported v0 configuration produces a `nemoclaw.nvidia.com/v1alpha1` document that the v1 parser and planner accept without a separate compatibility translator.

- v0 owns verification of the source configuration and projection into the v1 vocabulary.
- v1 remains authoritative for the target schema, defaults, validation, resources, and lifecycle behavior.
- Target-owned values should use v1 defaults instead of copying incidental v0 implementation details.
- Every supported source field must be preserved, transformed, defaulted intentionally, or recorded as deferred. It must not be silently discarded.
- The translator introduced by #11813 is temporary for the aligned scenario and should be removed or consolidated once direct consumption works.

This is a configuration projection, not resource adoption. It does not claim that v1 can discover or take ownership of an existing v0 deployment.

## Initial Compatibility Boundary

The first implementation should cover accepted Linux/Docker OpenClaw and Hermes configurations that use hosted inference providers. It should include the configuration exercised by the v0-to-v1 E2E path and preserve supported agent settings, authentication references, tools, and integrations.

The emitted document does not need to reproduce v0 and v1 implementation defaults byte-for-byte. It must express the same user intent while allowing v1 to own target defaults such as gateway engine/image, network CIDR, and sandbox image.

### Required mappings

| v0 export | v1 document | Decision |
| --- | --- | --- |
| `apiVersion: nemoclaw.nvidia.com/v1` | `nemoclaw.nvidia.com/v1alpha1` | Emit the v1 API version. |
| Gateway name and port | Managed gateway endpoint | Preserve the port; omit the v0-only name and use v1 defaults for target-owned gateway fields. |
| Sandbox image | v1 sandbox defaults | Verify the v0 source image as part of export provenance, but do not serialize it as the v1 target image when v1 owns that choice. |
| Provider logical name and API | Provider resource and driver | Preserve stable references and select the v1 `openai` or `anthropic` driver from the API contract. |
| Agent type | `sandbox.harness.kind` | Map OpenClaw and Hermes explicitly. |
| Agent execution, interface, and observability settings | Harness configuration | Preserve supported settings in the owning v1 section. |
| Agent inference and tool settings | Agent configuration | Preserve supported settings and resource references. |
| Hermes auth provider reference | Validated source-only binding | Validate the reference, then omit it where v1 derives the same binding from provider configuration. |
| Brave web search | Typed `webSearch` integration and `integrationRefs` | Preserve the integration as a named v1 resource and attach it to the agent. |
| Sandbox policy | v1 policy | Preserve the effective restrictions while adapting target paths and the runtime user. Review changes such as `sandbox:sandbox` to `1000:1000` and v1-owned paths (`/opt/fabric`, `/opt/nemoclaw`, `/app` for OpenClaw, and `/opt/hermes` for Hermes). |
| Names and references | v1 resource names | Validate or deterministically adapt them to the v1 slug rules without breaking references. |

## Deferred Compatibility

Supported v0 exports should eventually become useful fixtures for finding missing v1 capabilities. The initial change may defer the following rather than expanding the v1 contract in the same issue:

- managed vLLM;
- attached/external Ollama through the managed proxy;
- Podman-backed configurations.

Deferral must be explicit. The exporter must not silently emit a partial document or claim full v0 compatibility for these cases. Follow-up work should feed successful v0 exports into the v1 parser and planner to identify missing schema, defaulting, artifact, and lifecycle support.

Existing v0 export exclusions remain exclusions unless separately accepted, including custom images or build contexts, direct GPU assignment, mounts, messaging, non-Brave web search, proxy credentials, custom CA configuration, Hermes OAuth/tool gateways, other agent types, and unqualified local inference arrangements.

## Acceptance Criteria

- [ ] The mapping from the supported v0 boundary to v1 resources is documented and maintainer-reviewed before implementation.
- [ ] Raw output from the public v0 export command uses `nemoclaw.nvidia.com/v1alpha1` and is accepted by the actual v1 `Document::parse` path without a compatibility translator.
- [ ] The parsed document reaches a successful v1 plan for the accepted hosted OpenClaw and Hermes scenarios.
- [ ] User-controlled provider, route/tuning, agent, tool, authentication, integration, and supported policy intent is preserved.
- [ ] Target-owned gateway and sandbox values use v1 defaults rather than copying v0 implementation defaults.
- [ ] Policy transformations have focused evidence that the v1 runtime retains the intended restrictions and required target paths.
- [ ] Unsupported and deferred configurations fail with specific diagnostics; their data is not silently omitted.
- [ ] Cross-resource references, duplicate names, unsupported APIs, missing credentials, and invalid values have negative coverage.
- [ ] The #11813 compatibility translator is removed or bypassed for the directly compatible hosted scenario.
- [ ] Schema examples and command help that describe the export shape are updated with the implementation.
- [ ] Test artifacts retain the raw v0 export bytes and stable resource identifiers with credentials and sensitive values redacted.

Parser and plan success establish contract compatibility, not deployment parity. Live apply, unchanged re-apply, export/re-apply, and destroy evidence remains part of the E2E qualification work in #11810 and related children.

## Validation Plan

1. Generate fixtures through the public v0 export command rather than constructing only synthetic YAML.
2. Feed the raw output to the v1 parser/schema validation and planning path.
3. Compare normalized intent for the supported fields and references.
4. Exercise malformed, unsupported, and deferred inputs and assert specific failures.
5. Use the trusted E2E path for live lifecycle evidence where required; label any synthetic coverage clearly.

## Security Considerations

- Do not serialize credential values into the exported YAML or retained artifacts.
- Preserve credential references and validate that referenced providers exist.
- Treat policy adaptation as a security-sensitive mapping: do not weaken filesystem, process, network, or identity restrictions merely to make the document parse.
- Reject ambiguous or lossy mappings instead of guessing.

## References

- Parent epic: #10904
- Hosted parity bridge: #11813
- Deployment qualification: #11810
- v0 exporter research baseline: `ee148fc1465a096249365e03f61240f8fd719aa9`
- v1 schema research baseline: `0aba1a6f7c1f77167651e62db5e6311807a09c39`
- #11813 translator research baseline: `5b374d87`

Category: Config & Schema

- [x] Includes raw v0 export output and v1 parse/plan evidence in the validation contract
- [x] Records the ownership decision: adapt v0 output to the v1 contract
- [x] Separates initial hosted compatibility from deferred local-runtime coverage
- [x] Does not imply resource adoption or full deployment parity

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.