SoquetT becomes a protocol

[mpharrigan]

Switches the SoquetT union type alias to a typing.Protocol. This supports "duck typing", which is appropriate for the situation where SoquetT is used as a type annotation.

Specifically, SoquetT is now anything that has .shape and .item(*args). With the addition of these properties/methods to the Soquet class, now this is satisfied by Soquet and NDArray. Note: we can't use mypy to annotate things with NDArray[Soquet] now or before due to limitations in numpy.

When users or developers need to dispatch depending on whether a SoquetT is a single soquet or an array thereof, they should use the new BloqBuilder methods. The example from the new docstring:

        >>> soq_or_soqs: SoquetT
        ... if BloqBuilder.is_ndarray(soq_or_soqs):
        ...     first_soq = soq_or_soqs.reshape(-1).item(0)
        ... else:
        ...     # Note: `.item()` raises if not a single item.
        ...     first_soq = soq_or_soqs.item()

---

In the protocol implementations and bloq standard library, this PR:

• Adds the typing protocol and introduces new methods to Soquet
• Uses the type-narrowing idioms in the _infra/ and protocols modules. Following this, pytest passes but there are mypy issues in the bloqs/ standard library
• Then, uses the type-narrowing idioms in the bloqs/ standard library.
• uses new alias soq.dtype instead of soq.reg.dtype. (removed from this PR)

Regarding #1720: this PR shows the changes to the standard library that would be required to avoid isinstance(x, Soquet) checks

[mpharrigan]

I've force-pushed a more restrained set of changes. Note that pytest-quick passes following commit 8496830 which includes absolutely no changes to the bloqs/ subdirectory. The changes needed to satisfy the type checker are found in b8ff0f0

[mhucka]

/gemini review

[gemini-code-assist]

Code Review

This pull request refactors SoquetT from a Union to a typing.Protocol to better support duck typing. This is a significant improvement that makes the type system more flexible and expressive. The changes throughout the codebase to adopt the new SoquetT protocol and the BloqBuilder.is_single/is_ndarray type guards are well-executed. My review includes a couple of suggestions to improve type consistency in the BloqBuilder's free and split methods to fully align with the new protocol-based approach.