Add tractor.to_actor one-shot task API subpkg

[goodboy]

Add tractor.to_actor one-shot task API subpkg

Motivation

First cut at resolving #477: the .run_in_actor() "one shot"
single-remote-task style API is coupled to ActorNursery internals
(the secondary ._ria_nursery, portal result-marking sets and
backend-side reaper tasks) which complicates the spawn and
cancellation machinery and defers remote-error propagation to nursery
teardown. Adopting the parlance of sibling APIs (trio.to_thread,
anyio.to_process) we instead deliver a tractor.to_actor subpkg
composed purely from the lower level daemon-spawn + portal
primitives, moving error collection/propagation up into whatever
local trio scope encloses the call — and paving the way to fully
drop the ._ria_nursery machinery.

Summary of changes

• new tractor.to_actor subpkg exporting run(fn, **fn_kwargs) -> Any: spawn a subactor via ActorNursery.start_actor(), schedule
  fn as its lone remote task with Portal.run(), block waiting on
  and return its result, ALWAYS reaping the subactor via a
  finally-scoped Portal.cancel_actor(). Remote errors raise
  directly in the caller's task as boxed RemoteActorErrors.
  "Placement" opts: portal= re-uses a running actor (no
  spawn/reap), an= spawns from a caller-managed actor-nursery,
  neither opens a private call-scoped open_nursery() (implicitly
  booting the runtime, tunable via pass-through runtime_kwargs).
  Fail-fast pre-spawn validation: non-streaming async fn only,
  portal=/an= mutually exclusive, no runtime_kwargs alongside a
  placement opt. Legacy .run_in_actor() behavior untouched; its
  TODO/docstring now x-ref the successor API.
• tests/test_to_actor.py: 11-test suite covering all placement
  variants, remote-error relay (bare + inside a caller-managed an),
  portal re-use w/o implicit reap, the concurrent "worker-pool-ish"
  pattern (local trio task nursery scheduling one-shots against a
  shared an) and the 4 validation rejections.
• examples/parallelism/to_actor_one_shots.py: runnable demo
  (auto-collected by test_docs_examples.py) of the fully-implicit
  one-shot + the concurrent prime-check pattern, a mini version of
  the neighboring concurrent_actors_primes.py.

Future follow up

Tracked in #477 (see the landed-shape comment there),

• migrate in-repo .run_in_actor() usage (tests, examples, docs)
  to to_actor.run()
• emit a DeprecationWarning from .run_in_actor() (blocked on
  ^)
• drop the ._ria_nursery + ._cancel_after_result_on_exit
  machinery — in progress on the stacked drop_ria_nursery branch
  (result-waiting being re-scoped into the to_actor layer), see
  ai/conc-anal/ria_nursery_removal_plan.md
• docs nod from the .run_in_actor() autodoc entry
• maybe: the worker-pool "sugar" API layer (Do we need a streaming equivalent (sugar) for .run_in_actor()? #172)

(this pr content was generated in some part by claude-code)

[Copilot]

Pull request overview

Introduces a new tractor.to_actor subpackage providing a high-level, “one-shot” remote task invocation API built on existing ActorNursery.start_actor() + Portal.run() + Portal.cancel_actor() primitives, intended as the successor to ActorNursery.run_in_actor() (issue #477).

Changes:

• Adds tractor.to_actor.run() implementing one-shot subactor spawn/reuse, remote execution, and teardown behavior.
• Exposes the new subpackage at the top level (import tractor.to_actor) and documents the intended migration path from run_in_actor().
• Adds a dedicated test suite and a runnable example demonstrating concurrent one-shot usage patterns.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tractor/to_actor/_api.py	Implements the new to_actor.run() API and its helper routines.
tractor/to_actor/init.py	Defines the new tractor.to_actor public surface (re-export of run).
tractor/runtime/_supervise.py	Updates run_in_actor() notes/TODOs to point to the successor API.
tractor/init.py	Re-exports to_actor at the package top level.
tests/test_to_actor.py	Adds coverage for placement modes, error propagation, concurrency pattern, and validation.
examples/parallelism/to_actor_one_shots.py	Adds an example demonstrating implicit runtime boot and concurrent one-shots.
ai/prompt-io/prompts/issue_477.md	Adds the driver prompt used for the work.
ai/prompt-io/claude/20260702T154255Z_65bf9df5_prompt_io.raw.md	Adds raw AI output log for the work session.
ai/prompt-io/claude/20260702T154255Z_65bf9df5_prompt_io.md	Adds summarized AI output log for the work session.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.