[doc-only] docs: clarify cuda.core concurrency and thread-safety policy

[Andy-Jost]

Summary

Writes down cuda.core's concurrency and thread-safety expectations, which were previously agreed only in review threads (#2280) and a follow-up Slack discussion, but never documented. Adds a short user-facing policy page and a matching set of contributor-facing invariants. Docs only; no code or behavior changes.

The policy is intentionally minimal, per the discussion: state what users can rely on today without overcommitting to guarantees we would have to maintain long-term.

Policy

• Concurrent reads of a cuda.core object from multiple host threads are supported.
• Concurrent mutation of the same object is not supported; the application must provide external synchronization (as is customary for NumPy, CuPy, and PyTorch).
• The library protects the integrity of its own internal state, so concurrent reads of one object and concurrent use of distinct objects cannot corrupt the interpreter. This is an integrity guarantee only.
• Distinct objects can still collide through shared CUDA driver/context state (e.g. changing peer device access while another thread accesses affected memory); synchronizing those cases is also the caller's responsibility.

Changes

• docs/source/concurrency.rst: new user-facing "Concurrency and Thread Safety" page, linked into the docs toctree (docs/source/index.rst).
• cuda_core/AGENTS.md: new "Concurrency and free-threading" section for contributors and reviewers -- reads-safe/mutation boundary, prefer immutable designs, shared-driver-state collisions, guarding internal cached state only for legitimately-shared objects (not thread-local ones like Device, cf. Revert SMResource splitting fix, the problem was the test #2321), GIL-held entry points, and releasing the GIL before entering the driver from callback/__del__ paths.

Related Work

• Consolidates decisions from cuda.core: graph slot table for node attachment lifetimes #2280 (graph slot-table review) and the follow-up thread-safety discussion.
• Reflects the free-threading hardening in Fix threading issues in graphnode cleanup and SMResource splitting #2162, Add critical section guards to accessors #2215, Use atomic flag for buffer memory-attribute initialization #2216, Use setdefault for internal cache to ensure identity caching #2217.
• Part of EPIC EPIC: Support free-threading build #350.

[seberg]

Thanks, much nicer than what I could have come up with! And I don't have a concrete improvement thought.

(My small thoughts are at best if we are comfortable to say that e.g. memory pools is, I believe, safe and might seem mutable. And I suspect most things are thread-safe in the sense of not corrupting state, unless it's a green context or so, but I got a feeling that information likely wouldn't add much even if we were comfortable to note it.)

[seberg]

Yeah, I think there are a few objects where we want idempotency. But not everwhere (places that use dict.setdefault() to ensure this).

[github-actions]

Doc Preview CI
Preview removed because the pull request was closed or merged.