Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions .agents/skills/build-openshell-mxc-windows/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -168,6 +168,15 @@ neither. Both are skip-safe (they print a SKIP reason and exit 0 when
arch-appropriate task is always safe even without real MXC hardware. Neither
is part of `windows:ci`'s ordered contract, so invoke it explicitly.

For GB300 Windows ARM64 qualification, do not use the skip-safe developer task
as release evidence. `windows:test:mxc-gb300:arm64` runs the required
ProcessContainer subset and fails on any required `SKIP`.
`windows:qualify:mxc:gb300:contract` validates the static coverage matrix, and
`windows:qualify:mxc:gb300` runs the complete source, host, build/test, policy
E2E, and OpenClaw gate. Its inputs and evidence contract are documented in
`crates/openshell-driver-mxc/qualification/README.md`. Native-x64 NemoClaw and
x64 Windows results never satisfy this ARM64 contract.

For full validation, detect the Windows host architecture first and choose the
native lane dynamically:

Expand Down Expand Up @@ -257,6 +266,9 @@ crypto dependency builds.
| `windows:test:unsupported:arm64` | Re-runs the same focused contracts natively on ARM64. Rejects non-ARM64 hosts. |
| `windows:test:mxc-real:x64` | Runs the serial, ignored real-`wxc-exec` integration suite natively on x64 through the MSVC wrapper. Rejects non-x64 hosts. |
| `windows:test:mxc-real:arm64` | Runs the same real-`wxc-exec` suite natively on ARM64. Rejects non-ARM64 hosts. |
| `windows:test:mxc-gb300:arm64` | Runs the required native ARM64 ProcessContainer subset and fails when a test skips. |
| `windows:qualify:mxc:gb300:contract` | Validates the required/optional/unsupported/architecture-constrained GB300 matrix. |
| `windows:qualify:mxc:gb300` | Runs the fail-closed GB300 ARM64 gate and validates hash-bound evidence. |
| `windows:artifacts` | Reports size and SHA256 for release artifacts that exist. |
| `windows:ci` | Runs the full ordered x64-host Windows CI lane, plus ARM64 check/build when not skipped. |

Expand Down
11 changes: 11 additions & 0 deletions architecture/windows-msvc-build.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,10 @@ Windows validation is exposed through `tasks/windows.toml`:
| `windows:test:arm64` | Run the same suite natively on ARM64. |
| `windows:test:unsupported:x64` | Run focused gateway-composition tests for unsupported driver contracts. |
| `windows:test:unsupported:arm64` | Run the same focused contracts natively on ARM64. |
| `windows:test:mxc-real:arm64` | Run the native real-MXC developer suite; missing hardware remains skip-safe. |
| `windows:test:mxc-gb300:arm64` | Run the required real-MXC subset on native ARM64 and fail on any required skip. |
| `windows:qualify:mxc:gb300:contract` | Validate the static NVBug 6643699 scope matrix on any development host. |
| `windows:qualify:mxc:gb300` | Execute the complete native GB300 ARM64 gate and produce hash-bound evidence. |
| `windows:ci` | Run check, build, test, unsupported-contract tests, and artifact reporting. |

The Windows tasks call `tasks/scripts/windows-msvc.ps1`. The wrapper discovers
Expand Down Expand Up @@ -185,6 +189,13 @@ native rather than emulated coverage.

## Validation Contract

The generic real-MXC lanes are diagnostics and deliberately remain skip-safe.
They cannot establish hardware qualification when a prerequisite or backend is
absent. GB300 release evidence uses the separate fail-closed contract in
[`crates/openshell-driver-mxc/qualification/`](../crates/openshell-driver-mxc/qualification/README.md).
That matrix separates native Windows ARM64 evidence from x64-only NemoClaw and
Windows lanes, and records all hardware-dependent exclusions explicitly.

A successful Windows build report should include:

- x64 and ARM64 `cargo check` status.
Expand Down
14 changes: 11 additions & 3 deletions crates/openshell-driver-mxc/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -183,16 +183,24 @@ This example uses `process_container`. The `IsoSessionApp.dll` and

## Real-MXC test lane

Three tasks drive real `wxc-exec.exe` hardware; all are **skip-safe** — any test
or scenario that requires an absent binary or backend prints a SKIP reason and
exits 0 rather than failing.
The generic real-`wxc-exec.exe` tasks are **skip-safe**: a test or scenario that
requires an absent binary or backend prints a SKIP reason and exits 0. They are
useful developer diagnostics, but a skipped run is not qualification evidence.
The GB300 task is deliberately strict and fails on every required skip.

| Task | What it runs | When to use |
|---|---|---|
| `windows:test:mxc-real:x64` | `tests/wxc_exec_real.rs` — Tier-2 invoker tests with `--ignored --test-threads=1`, including an HTTPS request through the host proxy | Pre-merge on any Windows host that has `wxc-exec`; dry-run tests always pass; enforcement tests probe-gate themselves |
| `windows:test:mxc-real:arm64` | Native ARM64 `tests/wxc_exec_real.rs` with the same contract | Pre-merge on an ARM64 Windows host with `wxc-exec` |
| `windows:test:mxc-gb300:arm64` | Required ARM64 ProcessContainer cases from `tests/wxc_exec_real.rs`; rejects x64 and every required `SKIP` | GB300 qualification only; requires a live backend and all prerequisites |
| `windows:e2e:mxc` | `examples/run-mxc-e2e.ps1` — Tier-3 scenario runner, real binary, probe-gated | Demo box / nightly; needs the gateway + CLI binaries in the script directory |
| `windows:e2e:mxc:mock` | Same runner with `-Mock` — wiring-only, no real `wxc-exec` needed | Any Windows host (CI, dev machine); validates wiring and the network-reject scenario |
| `windows:qualify:mxc:gb300` | Complete source, host, ARM64 build/test, strict MXC, policy E2E, OpenClaw, and hash-bound evidence contract | Review/release evidence on a native GB300 Windows ARM64 host |

The exact required, optional, unsupported, and architecture-constrained GB300
matrix is documented and machine-validated in
[`qualification/`](qualification/README.md). Native-x64 NemoClaw and Windows x64
lanes are explicitly separate and cannot receive GB300 ARM64 credit.

**Probe script:** `examples/probe-mxc-host.ps1` is an operator/CI preflight that emits a JSON capability report
(OS build, wxc-exec path/version, dry-run exit code, per-backend trial result,
Expand Down
86 changes: 86 additions & 0 deletions crates/openshell-driver-mxc/qualification/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
# GB300 Windows ARM64 MXC qualification

This directory is the repository-owned qualification contract for NVBug 6643699.
It closes the test-plan ambiguity without treating it as a product defect.

[`gb300-woa.json`](gb300-woa.json) is the authoritative coverage matrix. Every
row declares its disposition, owner, architecture, hardware dependency,
prerequisites, command, pass criteria, skip policy, and required artifact roles.
[`validate.py`](validate.py) rejects a contract that weakens the required rows
and validates retained evidence by SHA256. [`run-gb300-woa.ps1`](run-gb300-woa.ps1)
executes the required native lane and produces that evidence.

## Scope decisions

- The release target is a **native GB300 Windows ARM64 host** using the MXC
`process_container` backend. WSL and emulated/cross-built test execution do
not receive credit.
- OpenClaw is the one required agent application because this repository owns
its MXC launch and dynamic-forwarding harness. The caller must supply a
versioned ARM64 Node.js binary and OpenClaw package.
- OpenShell does not choose or ship inference models. Model qualification and
additional agent applications are optional, application-owned evidence and
cannot replace an OpenShell/MXC gate.
- NemoClaw's native-x64 qualification guard is a separate application lane. It
cannot satisfy any GB300 ARM64 row. The bundled Node/OpenClaw install helper
is also x64-only; GB300 runs must not use its Node.js output.
- `isolation_session` is optional because it depends on the OS build,
`IsoSessionApp.dll`, and the `wxc-exec` build. Its absence does not weaken the
required ProcessContainer gate.
- MXC process-policy mapping, GPU passthrough, and interactive exec/connect are
unsupported. Windows Docker, Kubernetes, Podman, and VM drivers remain
unsupported. Host GPU presence is not evidence of MXC GPU passthrough.

## Coverage summary

The JSON manifest contains the full prerequisites, pass/fail criteria, and
artifact contract. This compact view makes the ownership boundary reviewable.

| Disposition | Coverage IDs | Owner boundary |
|---|---|---|
| Required | `contract-integrity`, `source-provenance`, `gb300-arm64-host`, `arm64-msvc-check`, `arm64-release-build`, `arm64-native-tests`, `arm64-unsupported-driver-contracts`, `processcontainer-real-mxc`, `processcontainer-policy-e2e`, `openclaw-arm64-forward` | OpenShell development owns repository tests; GB300 QA owns host execution and evidence; the agent-app owner supplies versioned ARM64 OpenClaw inputs |
| Optional | `isolation-session`, `provider-credential-injection`, `etw-ocsf-audit`, `local-inference-models`, `additional-agent-apps` | The named component or product owner decides whether to attach extra evidence |
| Unsupported | `wsl`, `windows-non-mxc-drivers`, `mxc-process-policy`, `mxc-gpu-passthrough`, `mxc-interactive-exec` | No qualification claim is permitted |
| Architecture-constrained | `nemoclaw-native-x64`, `node-openclaw-x64-installer`, `windows-x64-lanes` | Native x64 lanes stay separate and receive no GB300 ARM64 credit |

Required coverage is fail-closed: a missing prerequisite, `SKIP`, non-zero exit,
non-ARM64 result, missing artifact role, empty artifact, path outside the evidence
root, or SHA256 mismatch fails validation. Generic real-MXC developer tasks remain
skip-safe and are not qualification evidence.

## Validate the contract

Static validation and regression tests do not require Windows or MXC hardware:

```text
uv run python crates/openshell-driver-mxc/qualification/validate.py contract
uv run pytest python/openshell/gb300_mxc_qualification_test.py
```

## Execute on GB300

Start from a clean review commit based directly on the freshly fetched
`origin/windows` tip. Run from elevated native ARM64 PowerShell:

```powershell
$env:OPENSHELL_GB300_BASE_SHA = '<full origin/windows SHA>'
$env:OPENSHELL_GB300_HARDWARE_ATTESTATION = 'GB300'
$env:OPENSHELL_WXC_EXEC_PATH = 'C:\mxc-kit\bin\wxc-exec.exe'
$env:OPENSHELL_GB300_NODE_PATH = 'C:\path\to\arm64\node.exe'
$env:OPENSHELL_GB300_OPENCLAW_DIR = 'C:\path\to\node_modules\openclaw'
$env:OPENSHELL_GB300_EVIDENCE_DIR = 'D:\evidence\openshell-gb300-<run-id>'

mise run --skip-tools windows:qualify:mxc:gb300
```

The runner fetches `origin/windows`, rejects a moved or unrelated base, requires
a clean worktree, verifies the PE machine for `wxc-exec.exe` and `node.exe`, and
stages only tracked examples plus freshly built ARM64 binaries. It never treats
an existing source tree or an earlier result bundle as current evidence.

The evidence directory contains environment/source provenance, the MXC host
probe, command logs with timings, ARM64 binary hashes, the complete MXC policy
and OpenClaw bundles, `evidence.json`, and the final validation log. Do not put
provider credentials in command lines or retained files. Optional credential
coverage must use a scoped non-production credential and prove that retained
artifacts contain no secret value.
Loading
Loading