Guard WorkerPool and WorkerProxy against reentrant context usage — Closes #145

[conradbzura]

Summary

Adds single-use enforcement to WorkerPool and WorkerProxy context managers so that any second entry — whether reentrant or after a full enter/exit cycle — raises RuntimeError immediately rather than silently corrupting state.

The implementation introduces a generic @noreentry descriptor class in src/wool/utilities/noreentry.py. The descriptor exclusively decorates instance methods (bare functions and unbound calls are static errors caught at the type-check level via __call__ -> Never). Guard state for each instance is tracked via a weakref.WeakSet on the descriptor, keeping instances clean without namespace pollution. functools.update_wrapper and inspect.markcoroutinefunction ensure the wrapper is transparent to introspection. The decorator is applied to WorkerProxy.enter() and WorkerPool.__aenter__(). Both READMEs are updated to document the single-use contract.

Closes #145.

Proposed changes

src/wool/utilities/noreentry.py — new @noreentry descriptor

Implements noreentry as a descriptor class for single-use method guards. The decorator uses the descriptor protocol's __get__ to return a bound wrapper on instance access, and __call__ -> Never to reject bare function usage at the type-check level.

Guard state is tracked via a weakref.WeakSet on the descriptor instance — when an instance's guarded method is called, that instance is added to the WeakSet. Any subsequent call to the same method on the same instance detects the instance in the set and raises RuntimeError. This approach avoids polluting instance namespaces and automatically cleans up references when instances are garbage collected.

The decorator works with both sync and async methods. Attempting to use it on bare functions or call it directly (unbound style) raises TypeError at runtime and is flagged as a static type error via the Never return annotation on __call__.

src/wool/runtime/worker/proxy.py and pool.py — apply guard

@noreentry is applied to WorkerProxy.enter() and WorkerPool.__aenter__(). The :raises RuntimeError: docstring on each method is updated to document single-use semantics.

Documentation

README.md and src/wool/runtime/worker/README.md each receive a note on the single-use contract with a brief code example showing the correct pattern (create a new instance for a new context).

Test cases

#	Test Suite	Given	When	Then	Coverage Target
1	TestNoReentry	A class with a sync @noreentry method	Method is called for the first time	Returns normally	First-call success for bound sync method
2	TestNoReentry	A class with a sync @noreentry method called once	Method is called a second time on the same instance	Raises RuntimeError	Guard on second sync call
3	TestNoReentry	A class with an async @noreentry method	Method is awaited for the first time	Returns normally	First-call success for bound async method
4	TestNoReentry	A class with an async @noreentry method awaited once	Method is awaited a second time	Raises RuntimeError	Guard on second async call
5	TestNoReentry	Two instances of a class with a @noreentry method, first called	Method is called on the second instance	Returns normally	Per-instance isolation
6	TestNoReentry	A sync @noreentry method called once	Method is called a second time	RuntimeError message includes the method's __qualname__	Error message content
7	TestNoReentry	A class with an async @noreentry method	asyncio.iscoroutinefunction is called on the method	Returns True	Coroutine function introspection transparency
8	TestNoReentry	A class with a sync @noreentry method	__name__ is inspected on the decorated method	Equals the original function name	functools.wraps preservation
9	TestNoReentry	A class with two @noreentry methods; first called twice	Second method is called	Returns normally	Per-method dict key independence
10	TestNoReentry	A class with a @noreentry method	Method is accessed through the class (unbound)	Returns the descriptor itself	Descriptor protocol for unbound access
11	TestNoReentry	A @noreentry descriptor accessed unbound	Descriptor is called directly	Raises TypeError	Rejection of bare function usage
12	TestWorkerProxy	A WorkerProxy that has already been entered	enter() is called a second time	Raises RuntimeError	Reentrant entry guard on proxy
13	TestWorkerProxy	A WorkerProxy that has been entered and exited	enter() is called again	Raises RuntimeError	Post-exit re-entry guard on proxy
14	TestWorkerPool	A WorkerPool already entered via async with	Pool is entered again via async with	Raises RuntimeError	Reentrant entry guard on pool
15	TestWorkerPool	A WorkerPool entered and exited via async with	Pool is entered again via async with	Raises RuntimeError	Post-exit re-entry guard on pool