post-#472 docs follow ups

[goodboy]

Refine typed messaging and discovery examples

Motivation

PR #460 established the modern docs scaffold, while #472 retained the
content work needed to make its guides and examples accurately teach
current APIs. Typed messaging and discovery still needed deeper
coverage, and many docs-visible examples lacked consistent typing and
source style.

This pass documents the runtime's actual payload-validation and
discovery contracts, adds a real dedicated-registrar topology, and
makes the examples easier to read without changing their intentional
failure and debugging behavior.

Summary of changes

• Expand the typed-messaging guide around pld_spec, sender- versus
  receiver-side validation, custom codecs, and the current boundaries
  of per-task and per-dialog hooks.

• Add a standalone dedicated-registrar example under
  examples/discovery/. It uses an ephemeral address, bounded
  collision retries, atomic readiness publication, external sibling
  discovery, and validated cross-platform teardown.

• Apply the repository's typing, docstring, string, and 69-column
  conventions across 38 changed examples while preserving intentional
  debugger failures, cancellation races, and Trio reproducers.

Future follow up

• Promote dedicated-registrar lifecycle management into a public
  tractor.discovery subsystem, informed by Piker's attach-or-create
  service ownership and usable by pytest registry isolation.

• Complete typed Start contracts and sender-side RPC argument
  validation under Type-check RPC Start params from endpoint signatures #514.

• Continue the remaining content and real-world-example work
  under Docs content refinement pass (follow-up to #460) #472.

Links

• Follows the foundational docs rebuild in PR Docs (vibed) for serious: real documentation with a modern theme  #460.
• Partially addresses Docs content refinement pass (follow-up to #460) #472.
• Extends the typed-messaging work discussed in Type annotating Context.open_stream() (probably with msgspec.Struct subtype(s)) 😎 #365 and PR enc_hook & dec_hook factory (+ CI uv update) #376.
• Tracks typed Start validation follow-up in Type-check RPC Start params from endpoint signatures #514.

(this pr content was generated in some part by opencode using
gpt-5.6-sol (openai))

[Copilot]

🟡 Changes recommended

The new examples/dedicated_registrar.py uses a fixed port and has incomplete subprocess cleanup, which can make the examples-as-tests run flaky and potentially leak a background registrar process.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR updates the documentation and example scripts as follow-ups to the #472 work, primarily by tightening type annotations across examples and extending the discovery guide with a dedicated-registrar pattern example.

Changes:

• Add/expand type annotations across many examples/ scripts to make the docs/examples more type-explicit.
• Add a new examples/dedicated_registrar.py and document the “dedicated registrar” pattern in docs/guide/discovery.rst.
• Expand messaging guide discussion around typed payload contracts and codec hooks, with additional issue/PR references.

File summaries

File	Description
examples/uds_transport_actor_tree.py	Add explicit ActorNursery/Portal annotations in UDS transport example.
examples/typed_payloads.py	Add explicit ActorNursery/Portal annotations in typed payloads example.
examples/trio/send_chan_aclose_masks_beg.py	Add explicit return type to main() signature.
examples/trio/lockacquire_not_unmasked.py	Add TaskStatus typing and return annotations for async entry points.
examples/streaming_broadcast_fanout.py	Add ActorNursery/Portal/Nursery annotations in broadcast fanout example.
examples/service_discovery.py	Add typed main() signature and typed portal variables for discovery calls.
examples/service_daemon_discovery.py	Add ActorNursery/Portal/Nursery annotations in daemon discovery example.
examples/rpc_bidir_streaming.py	Add explicit Portal type annotation for spawned RPC server portal.
examples/remote_error_propagation.py	Add return annotations and typed real_actors list.
examples/quick_cluster.py	Add return annotation for main() and annotate nursery variable.
examples/parallelism/single_func.py	Add return annotations and type pid from to_actor.run.
examples/parallelism/concurrent_actors_primes.py	Add argument/variable typing throughout primes worker-pool example.
examples/nested_actor_tree.py	Add ActorNursery/Nursery/Portal annotations in nested-tree example.
examples/multiple_streams_one_portal.py	Add typing to function params/locals and reformat start_actor call.
examples/integration/mpi4py/inherit_parent_main.py	Add ActorNursery/Portal/result annotations in mpi4py integration example.
examples/infected_asyncio_echo_server.py	Add return annotations and typed Portal in asyncio infection example.
examples/full_fledged_streaming_service.py	Add/extend type annotations in streaming service example.
examples/dedicated_registrar.py	New example demonstrating a dedicated external registrar process and discovery through it.
examples/debugging/subactor_error.py	Add return annotation for main() in debugging example.
examples/debugging/subactor_breakpoint.py	Add return annotation for main() in debugging example.
examples/debugging/subactor_bp_in_ctx.py	Add return annotation for main() in debugging example.
examples/debugging/shielded_pause.py	Add return annotation for main() in debugging example.
examples/debugging/root_timeout_while_child_crashed.py	Add return annotation for main() in debugging example.
examples/debugging/root_self_cancelled_w_error.py	Add return annotation for main() in debugging example.
examples/debugging/root_cancelled_but_child_is_in_tty_lock.py	Add return annotation for main() in debugging example.
examples/debugging/root_actor_error.py	Add return annotation for main() in debugging example.
examples/debugging/root_actor_breakpoint.py	Add return annotation for main() in debugging example.
examples/debugging/pm_in_subactor.py	Add return annotation for main() in debugging example.
examples/debugging/per_actor_debug.py	Add return annotation for main() in debugging example.
examples/debugging/multi_subactors.py	Add return annotation for main() in debugging example.
examples/debugging/multi_subactor_root_errors.py	Add return annotation for main() in debugging example.
examples/debugging/multi_nested_subactors_error_up_through_nurseries.py	Add return annotation for main() in debugging example.
examples/debugging/multi_daemon_subactors.py	Add return annotation for main() in debugging example.
examples/debugging/fast_error_in_root_after_spawn.py	Add return annotation for main() in debugging example.
examples/asynchronous_generators.py	Add return annotation and type key locals in async generator example.
examples/actor_spawning_and_causality.py	Add return annotations for example functions.
examples/actor_spawning_and_causality_with_daemon.py	Add return annotations and type the spawned portal.
examples/a_trynamic_first_scene.py	Add return annotations and type the portal in discovery call.
docs/guide/msging.rst	Expand typed messaging roadmap/details and add references (#365, #376).
docs/guide/discovery.rst	Document the dedicated registrar pattern and include the new example.

Review details

Suppressed comments (1)

examples/dedicated_registrar.py:118

• The registrar subprocess cleanup suppresses TimeoutExpired but does not kill the process on timeout, which can leak a background daemon and cause later example runs to fail. Also, send_signal() can raise if the process already exited; it’s safer to suppress that and force-kill on timeout.

        # graceful SIGINT teardown of the standalone registrar.
        registrar.send_signal(signal.SIGINT)
        with suppress(subprocess.TimeoutExpired):
            registrar.wait(timeout=10)
        print('dedicated registrar shut down')

• Files reviewed: 40/40 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

At least one updated example introduces a concrete static-typing mismatch (accept_addr annotated too narrowly) that should be corrected to keep the examples type-consistent.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 42/42 changed files
• Comments generated: 1
• Review effort level: Lite