cuda-core: distinguish CUDA devices and contexts in the shared host API #1504

Root Device and simt::CudaContext both bundle a CUDA device handle with a context handle. The shared host API needs distinct device and context identities while preserving convenient initialization and correct resource ownership.

Requirements

• Define device and context responsibilities, including the relationship between a device and its primary or other contexts. Physical-device identity must not substitute for context identity.
• Specify context ownership, retaining/releasing, thread binding, and borrowed/foreign-handle lifetimes.
• Evaluate a separately named convenience handle or constructor that pairs a device and context without obscuring their distinction.
• Map root Device and simt::CudaContext users onto the shared model, including streams, allocations, events, modules, and functions. Preserve context compatibility checks and resource lifetimes.
• Provide an incremental migration path for One host runtime, step 2: cuda-oxide adopts the root cuda-core types and cuda_core::simt goes away #1460 and One host runtime, step 3: cuda-oxide adopts the root cuda-async types and cuda_async::simt goes away #1461, coordinating explicit global-context handling with Make with_global_device_context state explicit (Uninitialized | Available | Borrowed) #1403 and cleanup without implicit synchronization on drop.

Acceptance

Document the type and ownership model and provide migration examples for both programming models. Validate context identity and lifetimes across owned, borrowed, and foreign resources. Select the final type names and convenience-wrapper shape as part of the API design.

Source: root Device, SIMT CudaContext.

Public namespace design is tracked separately in #1505.

Implementation and closure (2026-10-30)

Implemented by #1603, which now explicitly closes this issue when merged into main: Device is the physical GPU; Context owns or borrows an actual CUDA context. Device::primary_context() provides the convenience constructor, and Context::device() exposes the physical identity. Handles retain their actual context; compatibility compares context handles, not ordinals. Owned, raw-borrowed and foreign-owner lifetimes and migration are documented in cuda-core/README.md and the runtime API. Shared-allocation/borrowed-handle tests cover context mismatch, thread binding and nonblocking completion retention. The async consumer migration continues in #1604.

The explicit thread-local global-context state/re-entry design is a separate unfinished follow-up in #1403; closing the device/context API distinction does not close that issue.