[Jim Garrison (garrison)]

Adds coheriq.resolve_impl(), so the implementation an acceleration candidate dispatches to can be reached directly.

Reviewable as two commits: the first adds the function, the second renames it from get_active_impl() for the reasons under Why resolve_impl below.

The problem

A class or function decorated with @domain.acceleration_candidate is replaced by a dispatching wrapper. For a class, the wrapper is a function object standing where the class name used to be, so construction works and nothing else does:

@domain.acceleration_candidate
class Thing:
    def __init__(self, n): self.n = n
    @classmethod
    def make(cls, n): return cls(n)

domain.materialize()

Thing(3)              # fine
isinstance(x, Thing)  # TypeError: isinstance() arg 2 must be a type, ...
Thing.make(4)         # TypeError: 'classmethod' object is not callable

__new__, subclassing, and introspection are unreachable for the same reason. This matters because swapping a Python data structure for a compiled one is a headline use case for this package, so class candidates aren't a corner case. The existing example already works around it: RaggedBatch.from_flat can't be a @classmethod, so it lives as the free function ragged_batch_from_flat.

For a function candidate the wrapper forwards calls faithfully, so the gap is narrower but real: what it hides is the implementation's identity. Which object is actually being called isn't answerable by calling it.

The change

resolve_impl(candidate) returns what the wrapper dispatches to — the domain default, or the enabled engine's override:

isinstance(x, coheriq.resolve_impl(RaggedBatch))
coheriq.resolve_impl(RaggedBatch).make(4)      # a @classmethod
coheriq.resolve_impl(compute) is engine_compute

Like calling a candidate, it resolves and freezes the implementation, so no engine can be enabled afterwards. That's why it's a function call and not an attribute — the side effect should look deliberate. It's the same side effect calling any candidate already has, not a new one. __wrapped__ (already set by functools.wraps) remains the escape hatch for the original, ignoring any engine, with no such side effect.

Also adds CoheriqTypeError(CoheriqUserError, TypeError), raised for a non-candidate. The dual inheritance means it's catchable both as CoheriqError and as a plain TypeError.

Why resolve_impl

The function was originally get_active_impl(). Two problems with that name, both fixed by the second commit:

• get_ reads as a side-effect-free accessor, and this call isn't one. It freezes the implementation permanently. Naming it get_ put the name at odds with the docstring, which has to warn about exactly that. resolve carries the effect in the verb, and it's already this codebase's word for the operation — _ensure_realized_impl, _resolve_domain, and the docstrings that describe a call as resolving the implementation.
• It was confusable with available_implementations()-style name-returning functions, in particular active_implementation() (Add available_engines() and active_implementation() introspection functions #14). That one returns an implementation's name; this returns the implementation object. The near-identical names implied a kinship that misrepresented the return types, so dropping the echo removes the collision — whereas spelling this one resolve_implementation() would have tightened it.

impl is kept rather than spelled out: it's what the code calls the object throughout, and the abbreviation is what distinguishes the object-returning function from the name-returning one.

The private wrapper attribute carrying the hook is renamed to _coheriq_resolve_impl to match, so the one place a reader looks to understand how the public function reaches the implementation doesn't still use the old vocabulary.

It accepts both kinds of candidate

An earlier draft restricted this to classes, on the reasoning that a function wrapper already forwards everything that matters. That was too strong — identity is a fair thing to ask for, whether to compare with is or to inspect the resolved function itself, and calling through the wrapper can never answer it.

Restricting it also protected nothing: calling a function candidate already freezes the domain, so refusing the direct route just leaves the indirect one open.

Design notes

A free function, not a method. mypy special-cases class decorators and won't substitute a decorator's return type onto the class symbol, so a RaggedBatch.resolve_impl() method errors at every call site. The alternatives were a mixin base (works, but imposes inheritance on domain authors) or a metaclass — rejected, because it conflicts with nanobind's metaclass for bound C++ types, and engines are exactly where nanobind shows up.

The signature is identity-preserving (_F -> _F, bound to Callable). Because of the existing if TYPE_CHECKING and isclass(f): return f branch, a decorated class reads to a type checker as a constructor callable rather than type[...] — and a decorated function matches that same shape. So a type[_T] return would be correct for classes and simply wrong for functions (it would claim type[int] for a function returning int). The identity signature is accurate for every input. The cost is that isinstance() against the result needs a cast; an overload can recover that later if it's worth it.

No default_impl() counterpart. The default implementation is only ever worth referencing from within default code — but that code only runs when the default is the active implementation, where active and default are the same thing. For the genuine remaining case (introspection, tests), __wrapped__ already covers it.

Caveat worth flagging

coheriq doesn't ship a py.typed marker, so downstream consumers currently see everything imported from coheriq as Any — which means the type-checking discussion above is dormant until that changes. I confirmed this empirically: from outside the package both calls reveal Any regardless of the signature. Adding the marker is tracked separately in #16 and isn't part of this PR.

The runtime motivation (isinstance / @classmethod / __new__ being broken, and function identity being unreachable) is live today regardless.

Testing

• tox -e py — 36 passed, of which 12 are new (TestResolveImpl)
• tox -e lint — green: ruff, copyright check, mypy, pylint 10.00/10 on src/ and test/, nbqa, reno
• tox -e doctest, tox -e docs — both green

New tests cover: resolution to the default class; isinstance and __new__ becoming usable; reflecting an active engine; the freeze side effect; __wrapped__ staying the original class under an active engine; rejection of non-candidates including the dual-catchability of the error; and, for function candidates, identity against both the default and an engine override, agreement between calling the result and calling the wrapper, and the freeze.

Notes

• resolve_impl and CoheriqTypeError are added to the API docs (user_functions.rst, exceptions.rst).
• Includes a release note.
• The branch name still says get-active-impl, predating the rename. Left alone deliberately, to keep this PR's URL and review history.
• This PR's docs don't cross-reference active_implementation, so that Add available_engines() and active_implementation() introspection functions #14 can land first without the two branches colliding. Restoring that xref is a follow-up on this branch once Add available_engines() and active_implementation() introspection functions #14 merges.
• Open question I left alone: whether the example's ragged_batch_from_flat should now revert to a @classmethod, to exercise this in the demo. Kept out to keep the diff focused.

---

This PR was generated by Claude Opus 5 under my guidance.

[Coveralls (coveralls)]

Coverage Report for CI Build 36934638601

Coverage increased (+1.1%) to 87.168%

Details

• Coverage increased (+1.1%) from the base build.
• Patch coverage: 13 of 13 lines across 3 files are fully covered (100%).
• No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	226
Covered Lines:	197
Line Coverage:	87.17%
Coverage Strength:	0.87 hits per line

---

💛 - Coveralls